@amerilux/netsuite-api 0.2.1 → 0.5.0

package/dist-tooling/config.d.ts

@@ -3,9 +3,40 @@ import type { FileSystemAdapter } from './file-system.js';
  * Settings of `netsuite-api generate`, read from netsuite-api.config.json at the project root. Every
  * path is relative to the config file; the defaults match the layout create-netsuite-project scaffolds.
  */
+/** A field of the run record, by the name the package's code uses for it. */
+export type JobRunFieldName = 'job' | 'status' | 'stage' | 'stagePercentComplete' | 'input' | 'result' | 'errors' | 'taskId' | 'deployment' | 'startedBy' | 'startedAt' | 'finishedAt';
+/**
+ * What each run field's id ends in, under the configured prefix: `custrecord_<prefix>_jr` plus
+ * `_status` is the status field. Short on purpose, because NetSuite caps a field id at 40 characters.
+ */
+export declare const JOB_RUN_FIELD_SUFFIXES: Record<JobRunFieldName, string>;
+export declare const netsuiteValueTypeNames: readonly ["text", "integer", "decimal", "checkbox", "date", "select"];
+export type NetsuiteValueTypeName = (typeof netsuiteValueTypeNames)[number];
+/**
+ * The run record as this application deployed it. The shape is the package's and the ids are the
+ * application's: `npm run add:jobs` writes the record with the application's prefix and puts the same
+ * ids here, and the generator copies them into the scripts map for the jobs and the run store to read.
+ */
+export interface JobRunsSettings {
+    /** The record type's id: `customrecord_<prefix>_job_run`. */
+    recordType: string;
+    /** What every field id starts with: `custrecord_<prefix>_jr`. */
+    fieldPrefix: string;
+    /** The id of a single field whose name in the account differs from prefix plus suffix. */
+    fields?: Partial<Record<JobRunFieldName, string>>;
+    /** Fields this application added to the record, by the name its code uses: what startJob may set and a run reports back. */
+    extraFields?: Record<string, {
+        id: string;
+        type: NetsuiteValueTypeName;
+    }>;
+}
 export interface ClientGeneratorConfig {
     /** Directory holding the controllers: one `<name>Controller.ts` per script. */
     controllers: string;
+    /** Directory holding the jobs: one `<name>.ts` per Map/Reduce script. A project with no such directory has no jobs. */
+    jobs: string;
+    /** The run record the jobs' runs live in. Left out until the project has jobs (`npm run add:jobs` adds it). */
+    jobRuns?: JobRunsSettings;
     /** The client's generated directory: one `<name>.gen.ts` per controller (its wire shapes, its endpoint type, its client) and `index.gen.ts` re-exporting each under the controller's name. Nothing else lives there. */
     outDir: string;
     /** The generated server-side `scripts` map: what a repository passes to createSuiteletClient. */
@@ -22,10 +53,13 @@ export interface ClientGeneratorConfig {
      */
     typeImports: Record<string, string>;
     /**
-     * Type-only files whose declarations are copied into the generated module of every controller
-     * that imports from them, as the specifier written in the controller mapped to the file: the
-     * generated entity types. A controller module carries the types it names, and what those refer
-     * to, so the client needs no copy of the file.
+     * Files whose type declarations are copied into the generated module of every controller that
+     * imports types from them, as the specifier written in the controller mapped to the file: the
+     * generated entity types, and the services (a key with one `*` stands for a file name:
+     * `../services/*` mapped to `api/src/services/*.ts`). A controller module carries the types it
+     * names and what those refer to, following an import from one listed file into another, so the
+     * client needs no copy of any of them. Only the type declarations of a file are read; a service's
+     * functions are not.
      */
     inlineTypes: Record<string, string>;
 }
@@ -35,10 +69,17 @@ export interface ResolvedClientGeneratorConfig extends ClientGeneratorConfig {
 }
 export declare const DEFAULT_CONFIG_FILE_NAME = "netsuite-api.config.json";
 export declare const defaultClientGeneratorConfig: ClientGeneratorConfig;
+/**
+ * The file an inlineTypes entry names for a specifier: the exact key, or a key with one `*` standing
+ * for a single path segment, substituted into the value. Undefined when no entry matches.
+ */
+export declare function resolveInlineTypesFile(inlineTypes: Record<string, string>, specifier: string): string | undefined;
 export declare class ClientGeneratorConfigError extends Error {
     readonly configPath: string;
     readonly problems: string[];
     constructor(configPath: string, problems: string[]);
 }
+/** Every run field's id: the prefix plus its suffix, or the override the config gives it. */
+export declare function resolveJobRunFieldIds(settings: JobRunsSettings): Record<JobRunFieldName, string>;
 /** Loads the config in the working directory (or the one named), applying the defaults for what it omits. */
 export declare function loadClientGeneratorConfig(fileSystem: FileSystemAdapter, cwd: string, configPath?: string): ResolvedClientGeneratorConfig;

package/dist-tooling/config.js

@@ -1,14 +1,57 @@
 import * as nodePath from 'node:path';
+/**
+ * What each run field's id ends in, under the configured prefix: `custrecord_<prefix>_jr` plus
+ * `_status` is the status field. Short on purpose, because NetSuite caps a field id at 40 characters.
+ */
+export const JOB_RUN_FIELD_SUFFIXES = {
+    job: '_job',
+    status: '_status',
+    stage: '_stage',
+    stagePercentComplete: '_percent',
+    input: '_input',
+    result: '_result',
+    errors: '_errors',
+    taskId: '_task',
+    deployment: '_deploy',
+    startedBy: '_by',
+    startedAt: '_start',
+    finishedAt: '_end',
+};
+export const netsuiteValueTypeNames = ['text', 'integer', 'decimal', 'checkbox', 'date', 'select'];
 export const DEFAULT_CONFIG_FILE_NAME = 'netsuite-api.config.json';
 export const defaultClientGeneratorConfig = {
     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' },
 };
+const wildcardInlineTypesKeyPattern = /^([^*]*)\*([^*]*)$/;
+const wildcardSegmentPattern = /^[A-Za-z0-9_-]+$/;
+/**
+ * The file an inlineTypes entry names for a specifier: the exact key, or a key with one `*` standing
+ * for a single path segment, substituted into the value. Undefined when no entry matches.
+ */
+export function resolveInlineTypesFile(inlineTypes, specifier) {
+    const exact = inlineTypes[specifier];
+    if (exact !== undefined)
+        return exact;
+    for (const [key, filePattern] of Object.entries(inlineTypes)) {
+        const wildcard = wildcardInlineTypesKeyPattern.exec(key);
+        if (!wildcard)
+            continue;
+        const [, prefix, suffix] = wildcard;
+        if (specifier.length <= prefix.length + suffix.length || !specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+            continue;
+        const segment = specifier.slice(prefix.length, specifier.length - suffix.length);
+        if (wildcardSegmentPattern.test(segment))
+            return filePattern.replace('*', segment);
+    }
+    return undefined;
+}
 export class ClientGeneratorConfigError extends Error {
     configPath;
     problems;
@@ -19,11 +62,71 @@ export class ClientGeneratorConfigError extends Error {
         this.name = 'ClientGeneratorConfigError';
     }
 }
-const stringSettings = ['controllers', 'outDir', 'scriptsOutFile', 'clientModule', 'wireModule'];
+const stringSettings = ['controllers', 'jobs', 'outDir', 'scriptsOutFile', 'clientModule', 'wireModule'];
 const mapSettings = ['typeImports', 'inlineTypes'];
 function isStringMap(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === 'string' && entry !== '');
 }
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** The run record block: the record's own ids, and the fields the application added to it. */
+function validateJobRunsSettings(raw, problems) {
+    if (!isPlainObject(raw)) {
+        problems.push("'jobRuns' must be an object with 'recordType' and 'fieldPrefix'.");
+        return undefined;
+    }
+    const recordType = raw.recordType;
+    const fieldPrefix = raw.fieldPrefix;
+    if (typeof recordType !== 'string' || recordType.trim() === '')
+        problems.push("'jobRuns.recordType' must be the run record's id, such as 'customrecord_app_job_run'.");
+    if (typeof fieldPrefix !== 'string' || fieldPrefix.trim() === '')
+        problems.push("'jobRuns.fieldPrefix' must be what the run record's field ids start with, such as 'custrecord_app_jr'.");
+    const settings = { recordType: String(recordType ?? ''), fieldPrefix: String(fieldPrefix ?? '') };
+    if (raw.fields !== undefined) {
+        if (!isStringMap(raw.fields))
+            problems.push("'jobRuns.fields' must be an object of strings: the fields whose ids differ from the prefix plus the usual suffix.");
+        else {
+            for (const name of Object.keys(raw.fields)) {
+                if (!(name in JOB_RUN_FIELD_SUFFIXES))
+                    problems.push(`'jobRuns.fields.${name}' is not a run field; the fields are ${Object.keys(JOB_RUN_FIELD_SUFFIXES).join(', ')}.`);
+            }
+            settings.fields = raw.fields;
+        }
+    }
+    if (raw.extraFields !== undefined) {
+        if (!isPlainObject(raw.extraFields))
+            problems.push("'jobRuns.extraFields' must be an object of { id, type } by field name.");
+        else {
+            const extraFields = {};
+            for (const [name, field] of Object.entries(raw.extraFields)) {
+                if (!isPlainObject(field) || typeof field.id !== 'string' || field.id === '') {
+                    problems.push(`'jobRuns.extraFields.${name}' needs 'id', the field's id in NetSuite.`);
+                    continue;
+                }
+                if (typeof field.type !== 'string' || !netsuiteValueTypeNames.includes(field.type)) {
+                    problems.push(`'jobRuns.extraFields.${name}.type' must be one of ${netsuiteValueTypeNames.map((value) => `'${value}'`).join(', ')}.`);
+                    continue;
+                }
+                extraFields[name] = { id: field.id, type: field.type };
+            }
+            settings.extraFields = extraFields;
+        }
+    }
+    for (const key of Object.keys(raw)) {
+        if (!['recordType', 'fieldPrefix', 'fields', 'extraFields'].includes(key))
+            problems.push(`'jobRuns.${key}' is not a setting.`);
+    }
+    return settings;
+}
+/** Every run field's id: the prefix plus its suffix, or the override the config gives it. */
+export function resolveJobRunFieldIds(settings) {
+    const ids = {};
+    for (const [name, suffix] of Object.entries(JOB_RUN_FIELD_SUFFIXES)) {
+        ids[name] = settings.fields?.[name] ?? `${settings.fieldPrefix}${suffix}`;
+    }
+    return ids;
+}
 function validateClientGeneratorConfig(raw, configPath) {
     const problems = [];
     const config = { ...defaultClientGeneratorConfig, typeImports: { ...defaultClientGeneratorConfig.typeImports }, inlineTypes: { ...defaultClientGeneratorConfig.inlineTypes } };
@@ -45,7 +148,18 @@ function validateClientGeneratorConfig(raw, configPath) {
         else
             problems.push(`'${setting}' must be an object of strings.`);
     }
-    const known = new Set([...stringSettings, ...mapSettings]);
+    for (const [key, filePattern] of Object.entries(config.inlineTypes)) {
+        const stars = (key.match(/\*/g) ?? []).length;
+        if (stars > 1)
+            problems.push(`'inlineTypes' key '${key}' has more than one '*'; one stands for the file name.`);
+        else if (stars === 1 && !filePattern.includes('*'))
+            problems.push(`'inlineTypes' key '${key}' has a '*' but its file '${filePattern}' has none to put the name in.`);
+        else if (stars === 0 && filePattern.includes('*'))
+            problems.push(`'inlineTypes' file '${filePattern}' has a '*' but its key '${key}' has none to take the name from.`);
+    }
+    if (raw.jobRuns !== undefined)
+        config.jobRuns = validateJobRunsSettings(raw.jobRuns, problems);
+    const known = new Set([...stringSettings, ...mapSettings, 'jobRuns']);
     for (const key of Object.keys(raw)) {
         if (!known.has(key))
             problems.push(`'${key}' is not a setting.`);

package/dist-tooling/controllerReader.d.ts

@@ -4,8 +4,8 @@ import ts from 'typescript';
  * defineRestlet or defineSuitelet call, the exported types (the DTOs), and the name, request type and
  * response type of every endpoint in its `defineEndpoints({ ... })`. A parse, not a type check: the
  * handler annotations are the contract, so they must be written out, a DTO may only reference types
- * from the inlined files, the carried modules or another controller, and the script ids are string
- * literals.
+ * from the inlined files (the entity types, the services), the carried modules or another controller,
+ * and the script ids are string literals.
  */
 export interface ControllerProblem {
     filePath: string;
@@ -84,6 +84,28 @@ export interface ControllerReadResult {
     problems: ControllerProblem[];
 }
 export declare function isControllerFileName(fileName: string): boolean;
+export declare function hasExportModifier(node: ts.Node): boolean;
 /** The JSDoc block directly above a node (no blank line between them), or undefined. */
 export declare function readLeadingJsDoc(node: ts.Node, sourceFile: ts.SourceFile): string | undefined;
+/** The script type NetSuite reads from the leading JSDoc, or undefined. */
+export declare function readScriptTypeHeader(source: string): string | undefined;
+export type ReadTypeImport = {
+    kind: 'carried';
+    typeImport: CarriedTypeImport;
+} | {
+    kind: 'inlined';
+    typeImport: InlinedTypeImport;
+} | {
+    kind: 'controller';
+    typeImport: ControllerTypeImport;
+};
+export declare function readTypeImport(statement: ts.ImportDeclaration, filePath: string, options: ReadControllerOptions): {
+    read?: ReadTypeImport;
+    problems: ControllerProblem[];
+};
+export declare function findCall(statement: ts.VariableStatement, calleeNames: string[]): {
+    declarationName: string;
+    call: ts.CallExpression;
+} | undefined;
+export declare function readStringProperty(literal: ts.ObjectLiteralExpression, propertyName: string): string | undefined;
 export declare function readControllerContract(filePath: string, source: string, options: ReadControllerOptions): ControllerReadResult;

package/dist-tooling/controllerReader.js

@@ -1,5 +1,6 @@
 import * as nodePath from 'node:path';
 import ts from 'typescript';
+import { resolveInlineTypesFile } from './config.js';
 import { toPosixPath } from './file-system.js';
 /** The return type a handler writes, exactly, to answer with a document instead of the envelope. */
 export const RAW_RESPONSE_TYPE_NAME = 'RawResponse';
@@ -16,7 +17,7 @@ const entryPointByFunction = {
 export function isControllerFileName(fileName) {
     return controllerFileNamePattern.test(fileName);
 }
-function hasExportModifier(node) {
+export function hasExportModifier(node) {
     return ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
 }
 /** The JSDoc block directly above a node (no blank line between them), or undefined. */
@@ -31,11 +32,11 @@ export function readLeadingJsDoc(node, sourceFile) {
     return sourceFile.text.slice(jsDocRange.pos, jsDocRange.end);
 }
 /** The script type NetSuite reads from the leading JSDoc, or undefined. */
-function readScriptTypeHeader(source) {
+export function readScriptTypeHeader(source) {
     const header = source.match(/^\s*(\/\*[\s\S]*?\*\/)/)?.[1] ?? '';
     return header.match(/@NScriptType\s+(\w+)/)?.[1];
 }
-function readTypeImport(statement, filePath, options) {
+export function readTypeImport(statement, filePath, options) {
     const problems = [];
     const clause = statement.importClause;
     if (!clause || !ts.isStringLiteral(statement.moduleSpecifier))
@@ -63,7 +64,7 @@ function readTypeImport(statement, filePath, options) {
     const sibling = siblingControllerSpecifierPattern.exec(moduleSpecifier);
     if (sibling)
         return { read: { kind: 'controller', typeImport: { controllerName: sibling[1], names } }, problems };
-    if (options.inlineTypes[moduleSpecifier] !== undefined)
+    if (resolveInlineTypesFile(options.inlineTypes, moduleSpecifier) !== undefined)
         return { read: { kind: 'inlined', typeImport: { specifier: moduleSpecifier, names } }, problems };
     const clientSpecifier = options.typeImports[moduleSpecifier];
     if (clientSpecifier !== undefined)
@@ -118,7 +119,7 @@ function readEndpoint(property, filePath, sourceFile) {
         problems,
     };
 }
-function findCall(statement, calleeNames) {
+export function findCall(statement, calleeNames) {
     for (const declaration of statement.declarationList.declarations) {
         if (!ts.isIdentifier(declaration.name))
             continue;
@@ -129,7 +130,7 @@ function findCall(statement, calleeNames) {
     }
     return undefined;
 }
-function readStringProperty(literal, propertyName) {
+export function readStringProperty(literal, propertyName) {
     for (const property of literal.properties) {
         if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === propertyName && ts.isStringLiteral(property.initializer))
             return property.initializer.text;

package/dist-tooling/emit.d.ts

@@ -1,10 +1,18 @@
 import type { ControllerContract, TypeDeclaration } from './controllerReader.js';
+import type { JobRunFieldName } from './config.js';
+import type { JobContract } from './jobReader.js';
 /**
  * Writes the generated modules. Each controller gets its own client module, `<name>.gen.ts`: the
- * entity types it names (copied in, so the module stands on its own), its wire shapes, its endpoint
- * type and, when the browser calls it, its client. The index module re-exports each one as a
+ * entity and service types it names (copied in, so the module stands on its own), its wire shapes,
+ * its endpoint type and, when the browser calls it, its client. The index module re-exports each one as a
  * namespace, so a hook writes `user.api.roles()` and names a shape as `user.RolesResponse`. The
  * scripts module is the server-side map a repository passes to createSuiteletClient.
+ *
+ * A job gets a module of the same kind, `<name>Job.gen.ts`, holding the shape a finished run carries
+ * (`Result`) and nothing callable: a page starts a job through a controller, not directly, and a run's
+ * input is the service's own type, named where the run is started rather than in the browser.
+ * They are reached under `jobs` (`jobs.closeStaleOrders.Result`). Server-side, the scripts module
+ * carries the jobs as well, and the run record's ids next to them.
  */
 /** The declarations copied from one inlined type file. */
 export interface InlinedTypeSection {
@@ -24,17 +32,51 @@ export interface EmitControllerModuleOptions {
 export interface EmitClientIndexModuleOptions {
     /** How the header names the sources: `api/src/controllers`. */
     controllersLabel: string;
+    /** True when the project has jobs, so the index re-exports them under `jobs`. */
+    hasJobs?: boolean;
+}
+/** The run record's ids as the scripts module writes them out. */
+export interface EmittedJobRuns {
+    recordType: string;
+    fields: Record<JobRunFieldName, string>;
+    extraFields: Record<string, {
+        id: string;
+        type: string;
+    }>;
 }
 export interface EmitScriptsModuleOptions {
     wireModule: string;
     controllersLabel: string;
+    /** The jobs to carry alongside the controllers, and where they came from. */
+    jobs?: EmittedJob[];
+    jobsLabel?: string;
+    /** The run record, written out when the project has one. */
+    jobRuns?: EmittedJobRuns;
 }
 /** The index module of the client, next to the controller modules: what a hook imports. */
 export declare const CLIENT_INDEX_FILE_NAME = "index.gen.ts";
+/** The module re-exporting every job module, reached as `jobs` from the client index. */
+export declare const JOBS_INDEX_FILE_NAME = "jobs.gen.ts";
 /** The client module of a controller: `user.gen.ts` for the user controller. */
 export declare function controllerModuleFileName(controllerName: string): string;
+/** The client module of a job: `closeStaleOrdersJob.gen.ts` for the closeStaleOrders job. */
+export declare function jobModuleFileName(jobName: string): string;
+/** A job as the generator writes it out: its contract, and the types copied in with it. */
+export interface EmittedJob {
+    contract: JobContract;
+    /** Where the file's header points a reader: the job's path relative to the project. */
+    sourceLabel: string;
+    inlinedTypes: InlinedTypeSection[];
+}
 export declare function emitControllerModule({ contract, sourceLabel, inlinedTypes }: EmittedController, options: EmitControllerModuleOptions): string;
 export declare function sortControllers(controllers: EmittedController[]): EmittedController[];
 /** The index module: every controller module re-exported under the controller's name. */
 export declare function emitClientIndexModule(controllers: EmittedController[], options: EmitClientIndexModuleOptions): string;
+export declare function sortJobs(jobs: EmittedJob[]): EmittedJob[];
+/** A job's module: the shapes a run is started with and ends in, and the types they are built from. */
+export declare function emitJobModule({ contract, sourceLabel, inlinedTypes }: EmittedJob): string;
+/** The jobs index: every job module under the job's name, reached as `jobs.<name>` from the client index. */
+export declare function emitJobsIndexModule(jobs: EmittedJob[], options: {
+    jobsLabel: string;
+}): string;
 export declare function emitScriptsModule(controllers: EmittedController[], options: EmitScriptsModuleOptions): string;

package/dist-tooling/emit.js

@@ -1,11 +1,21 @@
 import { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME } from './controllerReader.js';
+import { GENERATED_JOB_RESULT_TYPE_NAME } from './jobReader.js';
+import { readReferencedNames, writeDatesAsStrings } from './wireTypes.js';
 /** The index module of the client, next to the controller modules: what a hook imports. */
 export const CLIENT_INDEX_FILE_NAME = 'index.gen.ts';
+/** The module re-exporting every job module, reached as `jobs` from the client index. */
+export const JOBS_INDEX_FILE_NAME = 'jobs.gen.ts';
 /** The client module of a controller: `user.gen.ts` for the user controller. */
 export function controllerModuleFileName(controllerName) {
     return `${controllerName}.gen.ts`;
 }
+/** The client module of a job: `closeStaleOrdersJob.gen.ts` for the closeStaleOrders job. */
+export function jobModuleFileName(jobName) {
+    return `${jobName}Job.gen.ts`;
+}
 const INDENT = '    ';
+/** What a summarize stage returns when the run has no result to carry; the run record holds null either way. */
+const RESULTLESS_TYPE_NAMES = new Set(['void', 'undefined', 'null', 'never']);
 const EDIT_NOTICE = 'Do not edit: change the controller and run `npm run generate`.';
 const ESLINT_DISABLE = '/* eslint-disable */';
 function indentJsDoc(jsDoc) {
@@ -14,9 +24,10 @@ function indentJsDoc(jsDoc) {
         .map((line, index) => (index === 0 ? `${INDENT}${line.trim()}` : `${INDENT} ${line.trim()}`))
         .join('\n');
 }
+// A Date on the wire is an ISO string: the client module says so wherever a shape says Date.
 function emitEndpointMember(endpoint) {
-    const parameter = endpoint.requestType === undefined ? '' : `request${endpoint.requestOptional ? '?' : ''}: ${endpoint.requestType}`;
-    const member = `${INDENT}${endpoint.name}: (${parameter}) => ${endpoint.responseType};`;
+    const parameter = endpoint.requestType === undefined ? '' : `request${endpoint.requestOptional ? '?' : ''}: ${writeDatesAsStrings(endpoint.requestType, 'type')}`;
+    const member = `${INDENT}${endpoint.name}: (${parameter}) => ${writeDatesAsStrings(endpoint.responseType, 'type')};`;
     return endpoint.jsDoc ? `${indentJsDoc(endpoint.jsDoc)}\n${member}` : member;
 }
 function formatImportName(imported) {
@@ -55,12 +66,12 @@ export function emitControllerModule({ contract, sourceLabel, inlinedTypes }, op
     ];
     const sections = [header.join('\n'), imports.join('\n')];
     for (const section of inlinedTypes) {
-        sections.push(`// Entity types from ${section.sourceLabel}, copied so this module stands on its own.`);
+        sections.push(`// Types from ${section.sourceLabel}, copied so this module stands on its own.`);
         for (const declaration of section.declarations)
-            sections.push(declaration.text);
+            sections.push(writeDatesAsStrings(declaration.text, 'declaration'));
     }
     for (const declaration of contract.typeDeclarations)
-        sections.push(declaration.text);
+        sections.push(writeDatesAsStrings(declaration.text, 'declaration'));
     const members = contract.endpoints.map(emitEndpointMember);
     // A type alias, not an interface: only an object type literal satisfies the Endpoints index signature.
     sections.push(`/** The endpoint signatures of the ${contract.name} controller, as its handlers declare them. */\nexport type ${GENERATED_ENDPOINTS_TYPE_NAME} = {\n${members.join('\n')}\n};`);
@@ -84,21 +95,135 @@ export function emitClientIndexModule(controllers, options) {
             : `The ${contract.name} controller: its request and response types only; server code calls it, the browser does not.`;
         lines.push(`/** ${summary} */`, `export * as ${contract.name} from './${controllerModuleFileName(contract.name).replace(/\.ts$/, '')}';`);
     }
+    if (options.hasJobs) {
+        lines.push('/** Every job of this application: the shapes a run of each is started with and ends in. */', `export * as jobs from './${JOBS_INDEX_FILE_NAME.replace(/\.ts$/, '')}';`);
+    }
     return `${lines.join('\n')}\n`;
 }
+export function sortJobs(jobs) {
+    return [...jobs].sort((left, right) => left.contract.name.localeCompare(right.contract.name));
+}
+/** A job's module: the shapes a run is started with and ends in, and the types they are built from. */
+export function emitJobModule({ contract, sourceLabel, inlinedTypes }) {
+    // A job that answers nothing has no summarize, or one that returns nothing: either way the run's result is null,
+    // which is what the record holds and what the page reads back.
+    const resultType = contract.resultType === undefined || RESULTLESS_TYPE_NAMES.has(contract.resultType.trim()) ? 'null' : writeDatesAsStrings(contract.resultType, 'type');
+    // Only what the result names, because that is all this module declares: the shape a run is started with is
+    // the service's, named where the run is started, and a stage's own item types never leave the server.
+    const carried = findTypesReachedBy(resultType, contract.typeDeclarations, inlinedTypes);
+    const declarations = [];
+    for (const section of inlinedTypes) {
+        const kept = section.declarations.filter((declaration) => carried.has(declaration.name));
+        if (kept.length === 0)
+            continue;
+        declarations.push(`// Types from ${section.sourceLabel}, copied so this module stands on its own.`);
+        for (const declaration of kept)
+            declarations.push(writeDatesAsStrings(declaration.text, 'declaration'));
+    }
+    for (const declaration of contract.typeDeclarations) {
+        if (carried.has(declaration.name))
+            declarations.push(writeDatesAsStrings(declaration.text, 'declaration'));
+    }
+    // A job's stages name package types the result does not (JobSummary on summarize), and those are
+    // server-side: only an import a shape actually reaches is carried over.
+    const emittedText = [...declarations, resultType].join('\n');
+    const usedTypeImports = contract.carriedTypeImports
+        .map((typeImport) => ({ ...typeImport, names: typeImport.names.filter((imported) => new RegExp(`\\b${imported.alias ?? imported.name}\\b`).test(emittedText)) }))
+        .filter((typeImport) => typeImport.names.length > 0);
+    const sections = [
+        [
+            `// Generated by netsuite-api generate from ${sourceLabel}. Do not edit: change the job and run \`npm run generate\`.`,
+            '// A job is started through a controller, so this module carries its types and nothing callable.',
+            ESLINT_DISABLE,
+        ].join('\n'),
+        emitTypeImports(usedTypeImports).join('\n'),
+        ...declarations,
+    ];
+    sections.push(`/** What a finished run of the ${contract.name} job carries as its result. */\nexport type ${GENERATED_JOB_RESULT_TYPE_NAME} = ${resultType};`);
+    return `${sections.filter((section) => section !== '').join('\n\n')}\n`;
+}
+/**
+ * The declared shapes a type names, and the shapes those name in turn: what a module has to carry for the
+ * type to stand on its own. A name with no declaration here belongs to the package or to the language, and
+ * the type import that brought it is what carries it.
+ */
+function findTypesReachedBy(type, ownDeclarations, inlinedTypes) {
+    const declarationsByName = new Map();
+    for (const section of inlinedTypes)
+        for (const declaration of section.declarations)
+            declarationsByName.set(declaration.name, declaration.text);
+    for (const declaration of ownDeclarations)
+        declarationsByName.set(declaration.name, declaration.text);
+    const carried = new Set();
+    const pending = readReferencedNames(type, 'type');
+    while (pending.length > 0) {
+        const name = pending.shift();
+        if (carried.has(name))
+            continue;
+        const text = declarationsByName.get(name);
+        if (text === undefined)
+            continue;
+        carried.add(name);
+        pending.push(...readReferencedNames(text, 'declaration'));
+    }
+    return carried;
+}
+/** The jobs index: every job module under the job's name, reached as `jobs.<name>` from the client index. */
+export function emitJobsIndexModule(jobs, options) {
+    const lines = [`// Generated by netsuite-api generate from ${options.jobsLabel}. Do not edit: change the jobs and run \`npm run generate\`.`, ESLINT_DISABLE, ''];
+    for (const { contract } of sortJobs(jobs)) {
+        lines.push(`/** The ${contract.name} job: the shape a finished run of it carries. */`, `export * as ${contract.name} from './${jobModuleFileName(contract.name).replace(/\.ts$/, '')}';`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** The job reference as the scripts module writes it: what startJob submits. */
+function emitJobRef(contract) {
+    const { scriptId, deployments, runParameter, parameters } = contract.script;
+    const deploymentList = deployments.map((deployment) => `'${deployment}'`).join(', ');
+    const parameterEntries = parameters.map((parameter) => `${parameter.name}: '${parameter.id}'`).join(', ');
+    const parameterProperty = parameters.length > 0 ? `, parameters: { ${parameterEntries} }` : '';
+    return `{ kind: 'mapreduce', name: '${contract.name}', scriptId: '${scriptId}', deployments: [${deploymentList}], runParameter: '${runParameter}'${parameterProperty} }`;
+}
+function emitJobRunsConfig(jobRuns) {
+    const fieldEntries = Object.entries(jobRuns.fields).map(([name, id]) => `${INDENT}${INDENT}${name}: '${id}',`);
+    const extraEntries = Object.entries(jobRuns.extraFields).map(([name, field]) => `${INDENT}${INDENT}${name}: { id: '${field.id}', type: '${field.type}' },`);
+    return [
+        '/** The run record this application deployed: what a job and the run store read and write a run through. */',
+        'export const jobRuns = {',
+        `${INDENT}recordType: '${jobRuns.recordType}',`,
+        `${INDENT}fields: {`,
+        ...fieldEntries,
+        `${INDENT}},`,
+        ...(extraEntries.length > 0 ? [`${INDENT}extraFields: {`, ...extraEntries, `${INDENT}},`] : [`${INDENT}extraFields: {},`]),
+        '} as const satisfies JobRunsConfig;',
+    ];
+}
 export function emitScriptsModule(controllers, options) {
     const ordered = sortControllers(controllers);
     const entries = ordered.map(({ contract }) => `${INDENT}${contract.name}: ${emitScriptRef(contract.script)},`);
+    const jobs = sortJobs(options.jobs ?? []);
+    const importedTypes = ['ScriptRef', ...(jobs.length > 0 ? ['JobRef'] : []), ...(options.jobRuns ? ['JobRunsConfig'] : [])].sort();
+    const sourceLabels = [options.controllersLabel, ...(jobs.length > 0 && options.jobsLabel ? [options.jobsLabel] : [])].join(' and ');
     return [
-        `// Generated by netsuite-api generate from ${options.controllersLabel}. ${EDIT_NOTICE}`,
+        `// Generated by netsuite-api generate from ${sourceLabels}. ${EDIT_NOTICE}`,
         ESLINT_DISABLE,
         '',
-        `import type { ScriptRef } from '${options.wireModule}';`,
+        `import type { ${importedTypes.join(', ')} } from '${options.wireModule}';`,
         '',
         '/** Every script the controllers declare, by controller name: what a repository passes to createSuiteletClient. */',
         'export const scripts = {',
         ...entries,
         '} as const satisfies Record<string, ScriptRef>;',
+        ...(jobs.length > 0
+            ? [
+                '',
+                '/** Every job, by name: what a repository passes to the run store to start one. */',
+                'export const jobs = {',
+                ...jobs.map(({ contract }) => `${INDENT}${contract.name}: ${emitJobRef(contract)},`),
+                '} as const satisfies Record<string, JobRef>;',
+            ]
+            : []),
+        ...(options.jobRuns ? ['', ...emitJobRunsConfig(options.jobRuns)] : []),
         '',
     ].join('\n');
 }

package/dist-tooling/generate.d.ts

@@ -12,17 +12,26 @@ export interface PlannedController {
     browser: boolean;
     endpointCount: number;
 }
+export interface PlannedJob {
+    name: string;
+    filePath: string;
+    /** The stages the job declares, in the order NetSuite calls them. */
+    stages: string[];
+    /** How many deployments a run can be started on: how many runs of the job can overlap. */
+    deploymentCount: number;
+}
 export interface PlannedFile {
     /** Absolute path. */
     path: string;
     content: string;
 }
 export interface ClientGenerationPlan {
-    /** The modules to write: one per controller, the client index, the scripts map; empty when there are problems. */
+    /** The modules to write: one per controller and per job, the client index, the jobs index, the scripts map; empty when there are problems. */
     files: PlannedFile[];
     /** Generated files in the client's output directory the plan does not write: a removed controller's module, or the copy of the entity types an earlier version made. Absolute paths. */
     leftoverFiles: string[];
     controllers: PlannedController[];
+    jobs: PlannedJob[];
     problems: ControllerProblem[];
 }
 export interface ClientGenerationResult extends ClientGenerationPlan {