@amerilux/netsuite-api 0.4.0 → 0.5.0

package/dist-tooling/config.js

@@ -1,7 +1,27 @@
 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',
@@ -42,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 } };
@@ -77,7 +157,9 @@ function validateClientGeneratorConfig(raw, configPath) {
         else if (stars === 0 && filePattern.includes('*'))
             problems.push(`'inlineTypes' file '${filePattern}' has a '*' but its key '${key}' has none to take the name from.`);
     }
-    const known = new Set([...stringSettings, ...mapSettings]);
+    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

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

@@ -17,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. */
@@ -32,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))
@@ -119,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;
@@ -130,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 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,12 +1,21 @@
 import { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME } from './controllerReader.js';
-import { writeDatesAsStrings } from './wireTypes.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) {
@@ -86,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 {

package/dist-tooling/generate.js

@@ -1,7 +1,8 @@
 import * as nodePath from 'node:path';
-import { resolveInlineTypesFile } from './config.js';
+import { resolveInlineTypesFile, resolveJobRunFieldIds } from './config.js';
 import { isControllerFileName, readControllerContract } from './controllerReader.js';
-import { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule, sortControllers } from './emit.js';
+import { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName, sortControllers, sortJobs, } from './emit.js';
+import { isJobFileName, readJobContract } from './jobReader.js';
 import { toPosixPath } from './file-system.js';
 import { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
 import { readReferencedNames } from './wireTypes.js';
@@ -9,35 +10,71 @@ const generatedFileNamePattern = /\.gen\.ts$/;
 function relativeLabel(rootDirectory, filePath) {
     return toPosixPath(nodePath.relative(rootDirectory, filePath));
 }
-function findDuplicateScriptIds(controllers) {
+function findDuplicateScriptIds(controllers, jobs) {
     const problems = [];
-    for (const property of ['scriptId', 'deployId']) {
-        const owners = new Map();
-        for (const { contract } of controllers) {
-            const id = contract.script[property];
-            const owner = owners.get(id);
-            if (owner !== undefined)
-                problems.push({ filePath: contract.filePath, message: `${property} '${id}' is also declared by ${owner}; every controller is its own script.` });
-            else
-                owners.set(id, contract.filePath);
-        }
+    const scriptOwners = new Map();
+    const deployOwners = new Map();
+    const claim = (owners, id, filePath, label) => {
+        const owner = owners.get(id);
+        if (owner !== undefined)
+            problems.push({ filePath, message: `${label} '${id}' is also declared by ${owner}; every controller and every job is its own script.` });
+        else
+            owners.set(id, filePath);
+    };
+    for (const { contract } of controllers) {
+        claim(scriptOwners, contract.script.scriptId, contract.filePath, 'scriptId');
+        claim(deployOwners, contract.script.deployId, contract.filePath, 'deployId');
+    }
+    for (const { contract } of jobs) {
+        claim(scriptOwners, contract.script.scriptId, contract.filePath, 'scriptId');
+        for (const deployment of contract.script.deployments)
+            claim(deployOwners, deployment, contract.filePath, 'deployment');
     }
     return problems;
 }
-/**
- * A Date reached from a request shape, through the controller's own declarations and the copied
- * ones: the handler would receive an ISO string where its annotation promises a Date. (A shape taken
- * from a sibling controller is checked where it is declared, as that controller's own request.)
- */
-function findDatesInRequestShapes(contract, inlinedTypes, controllerLabel) {
+/** Every type declaration a shape can be built from: the file's own, then the ones copied into it. */
+function collectDeclarations(own, inlinedTypes) {
     const declarations = new Map();
-    for (const declaration of contract.typeDeclarations)
+    for (const declaration of own)
         declarations.set(declaration.name, declaration.text);
     for (const section of inlinedTypes) {
         for (const declaration of section.declarations)
             if (!declarations.has(declaration.name))
                 declarations.set(declaration.name, declaration.text);
     }
+    return declarations;
+}
+/**
+ * A Date reached from a run's input: it is stored as JSON on the run record, so the stage would
+ * receive an ISO string where its annotation promises a Date. The result is not checked, because
+ * nothing reads it back as a Date; the browser sees whatever summarize wrote.
+ */
+function findDatesInJobInput(contract, inlinedTypes, jobLabel) {
+    if (contract.inputType === undefined)
+        return [];
+    const declarations = collectDeclarations(contract.typeDeclarations, inlinedTypes);
+    const visited = new Set();
+    const pending = readReferencedNames(contract.inputType, 'type').map((name) => ({ name, via: contract.inputType }));
+    while (pending.length > 0) {
+        const { name, via } = pending.shift();
+        if (name === 'Date') {
+            return [{ filePath: jobLabel, message: `getInputData takes a Date in its input (through ${via}); a run carries its input as JSON, so take a string and parse it in the stage.` }];
+        }
+        const text = declarations.get(name);
+        if (text === undefined || visited.has(name))
+            continue;
+        visited.add(name);
+        pending.push(...readReferencedNames(text, 'declaration').map((reference) => ({ name: reference, via: name })));
+    }
+    return [];
+}
+/**
+ * A Date reached from a request shape, through the controller's own declarations and the copied
+ * ones: the handler would receive an ISO string where its annotation promises a Date. (A shape taken
+ * from a sibling controller is checked where it is declared, as that controller's own request.)
+ */
+function findDatesInRequestShapes(contract, inlinedTypes, controllerLabel) {
+    const declarations = collectDeclarations(contract.typeDeclarations, inlinedTypes);
     const problems = [];
     for (const endpoint of contract.endpoints) {
         if (endpoint.requestType === undefined)
@@ -132,7 +169,48 @@ export function planClientGeneration({ config, fileSystem }) {
         problems.push(...findDatesInRequestShapes(contract, inlinedTypes, controllerLabel));
         emitted.push({ contract, sourceLabel: controllerLabel, inlinedTypes });
     }
-    problems.push(...findDuplicateScriptIds(emitted));
+    // Jobs: the same reading, with a run instead of a request and a record instead of a reply.
+    const jobsDirectory = resolve(config.jobs);
+    const emittedJobs = [];
+    for (const filePath of fileSystem.listFiles(jobsDirectory)) {
+        const jobLabel = label(filePath);
+        if (!isJobFileName(nodePath.basename(filePath))) {
+            problems.push({ filePath: jobLabel, message: 'a job file is named <name>.ts, with <name> in camelCase; nothing else lives in the jobs folder.' });
+            continue;
+        }
+        const result = readJobContract(jobLabel, fileSystem.readTextFile(filePath), { typeImports: config.typeImports, inlineTypes: config.inlineTypes });
+        problems.push(...result.problems);
+        const contract = result.contract;
+        if (!contract)
+            continue;
+        if (controllerNames.has(contract.name) && jobModuleFileName(contract.name) === controllerModuleFileName(contract.name)) {
+            problems.push({ filePath: jobLabel, message: `a controller is named '${contract.name}' too; their generated modules would be the same file.` });
+        }
+        const inlinedTypes = [];
+        for (const typeImport of contract.inlinedTypeImports) {
+            const file = readInlinable(typeImport.specifier);
+            if (!file || file === 'missing')
+                continue;
+            const selected = selectInlinedTypes(file, typeImport.names, jobLabel, readInlinable);
+            problems.push(...selected.problems);
+            for (const selectedSection of selected.sections) {
+                const section = inlinedTypes.find((existing) => existing.sourceLabel === selectedSection.filePath);
+                if (section)
+                    section.declarations.push(...selectedSection.declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
+                else
+                    inlinedTypes.push({ sourceLabel: selectedSection.filePath, declarations: selectedSection.declarations });
+            }
+        }
+        problems.push(...findDatesInJobInput(contract, inlinedTypes, jobLabel));
+        emittedJobs.push({ contract, sourceLabel: jobLabel, inlinedTypes });
+    }
+    if (emittedJobs.length > 0 && config.jobRuns === undefined) {
+        problems.push({
+            filePath: label(jobsDirectory),
+            message: 'the project has jobs but no run record: add the `jobRuns` block to netsuite-api.config.json (`npm run add:jobs` writes it, with the record itself).',
+        });
+    }
+    problems.push(...findDuplicateScriptIds(emitted, emittedJobs));
     const controllers = emitted.map(({ contract }) => ({
         name: contract.name,
         filePath: contract.filePath,
@@ -140,19 +218,31 @@ export function planClientGeneration({ config, fileSystem }) {
         browser: contract.script.browser,
         endpointCount: contract.endpoints.length,
     }));
+    const jobs = emittedJobs.map(({ contract }) => ({
+        name: contract.name,
+        filePath: contract.filePath,
+        stages: contract.stages,
+        deploymentCount: contract.script.deployments.length,
+    }));
     if (problems.length > 0)
-        return { files: [], leftoverFiles: [], controllers, problems };
+        return { files: [], leftoverFiles: [], controllers, jobs, problems };
     const controllersLabel = label(controllersDirectory);
+    const jobsLabel = label(jobsDirectory);
+    const jobRuns = config.jobRuns
+        ? { recordType: config.jobRuns.recordType, fields: resolveJobRunFieldIds(config.jobRuns), extraFields: config.jobRuns.extraFields ?? {} }
+        : undefined;
     const files = [
         ...sortControllers(emitted).map((controller) => ({
             path: nodePath.join(outDirectory, controllerModuleFileName(controller.contract.name)),
             content: emitControllerModule(controller, { clientModule: config.clientModule }),
         })),
-        { path: nodePath.join(outDirectory, CLIENT_INDEX_FILE_NAME), content: emitClientIndexModule(emitted, { controllersLabel }) },
-        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel }) },
+        ...sortJobs(emittedJobs).map((job) => ({ path: nodePath.join(outDirectory, jobModuleFileName(job.contract.name)), content: emitJobModule(job) })),
+        ...(emittedJobs.length > 0 ? [{ path: nodePath.join(outDirectory, JOBS_INDEX_FILE_NAME), content: emitJobsIndexModule(emittedJobs, { jobsLabel }) }] : []),
+        { path: nodePath.join(outDirectory, CLIENT_INDEX_FILE_NAME), content: emitClientIndexModule(emitted, { controllersLabel, hasJobs: emittedJobs.length > 0 }) },
+        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel, jobs: emittedJobs, jobsLabel, jobRuns }) },
     ];
     const leftoverFiles = findLeftoverFiles(fileSystem, outDirectory, files.map((file) => file.path));
-    return { files, leftoverFiles, controllers, problems };
+    return { files, leftoverFiles, controllers, jobs, problems };
 }
 export function runClientGeneration(options) {
     const plan = planClientGeneration(options);