@amerilux/netsuite-api 0.1.0

package/dist-tooling/appReader.d.ts

@@ -0,0 +1,12 @@
+import type { ControllerProblem } from './controllerReader.js';
+/**
+ * Reads the project's app file (netsuite.ts): the application's names and the ids no controller or
+ * model owns. The client module carries it verbatim, so the file is plain declarations: exported
+ * constants and types, no imports, nothing that runs. The generator names anything else.
+ */
+export interface AppDeclarations {
+    /** Every exported declaration as written, JSDoc included, in file order. */
+    declarations: string[];
+    problems: ControllerProblem[];
+}
+export declare function readAppDeclarations(filePath: string, source: string): AppDeclarations;

package/dist-tooling/appReader.js

@@ -0,0 +1,31 @@
+import ts from 'typescript';
+import { readLeadingJsDoc } from './controllerReader.js';
+function hasExportModifier(node) {
+    return ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+function describeStatement(statement, sourceFile) {
+    return statement.getText(sourceFile).split('\n')[0].trim();
+}
+export function readAppDeclarations(filePath, source) {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const declarations = [];
+    const problems = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            problems.push({ filePath, message: `imports nothing: it is copied into the client module verbatim (found ${describeStatement(statement, sourceFile)}).` });
+            continue;
+        }
+        const isDeclaration = ts.isVariableStatement(statement) || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement);
+        if (!isDeclaration || !hasExportModifier(statement)) {
+            problems.push({ filePath, message: `holds exported constants and types only, because the client module carries it verbatim (found ${describeStatement(statement, sourceFile)}).` });
+            continue;
+        }
+        if (ts.isVariableStatement(statement) && !(statement.declarationList.flags & ts.NodeFlags.Const)) {
+            problems.push({ filePath, message: `exports constants only (found ${describeStatement(statement, sourceFile)}).` });
+            continue;
+        }
+        const jsDoc = readLeadingJsDoc(statement, sourceFile);
+        declarations.push(`${jsDoc ? `${jsDoc}\n` : ''}${statement.getText(sourceFile)}`);
+    }
+    return { declarations, problems };
+}

package/dist-tooling/cli/arguments.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedCommandLine {
+    command?: string;
+    options: Record<string, string | boolean>;
+    positional: string[];
+}
+/** Parses `command --key value --key=value --flag positional` without any dependency. */
+export declare function parseCommandLineArguments(argv: string[]): ParsedCommandLine;
+export declare function readStringOption(options: Record<string, string | boolean>, name: string): string | undefined;
+export declare function readFlagOption(options: Record<string, string | boolean>, name: string): boolean;

package/dist-tooling/cli/arguments.js

@@ -0,0 +1,34 @@
+/** Parses `command --key value --key=value --flag positional` without any dependency. */
+export function parseCommandLineArguments(argv) {
+    const parsed = { options: {}, positional: [] };
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        if (argument.startsWith('--')) {
+            const body = argument.slice(2);
+            const equalsIndex = body.indexOf('=');
+            if (equalsIndex >= 0) {
+                parsed.options[body.slice(0, equalsIndex)] = body.slice(equalsIndex + 1);
+            }
+            else if (index + 1 < argv.length && !argv[index + 1].startsWith('--')) {
+                parsed.options[body] = argv[++index];
+            }
+            else {
+                parsed.options[body] = true;
+            }
+        }
+        else if (parsed.command === undefined) {
+            parsed.command = argument;
+        }
+        else {
+            parsed.positional.push(argument);
+        }
+    }
+    return parsed;
+}
+export function readStringOption(options, name) {
+    const value = options[name];
+    return typeof value === 'string' ? value : undefined;
+}
+export function readFlagOption(options, name) {
+    return options[name] === true || options[name] === 'true';
+}

package/dist-tooling/cli/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist-tooling/cli/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from './main.js';
+process.exit(runCli(process.argv.slice(2), {
+    cwd: process.cwd(),
+    stdout: (message) => console.log(message),
+    stderr: (message) => console.error(message),
+}));

package/dist-tooling/cli/main.d.ts

@@ -0,0 +1,13 @@
+import type { FileSystemAdapter } from '../file-system.js';
+export interface CliEnvironment {
+    cwd: string;
+    fileSystem?: FileSystemAdapter;
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+}
+export declare const CLI_USAGE: string;
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_PROBLEMS = 1;
+export declare const EXIT_USAGE = 2;
+/** Runs the CLI and resolves to the process exit code. Never throws for user errors. */
+export declare function runCli(argv: string[], environment: CliEnvironment): number;

package/dist-tooling/cli/main.js

@@ -0,0 +1,88 @@
+import * as nodePath from 'node:path';
+import { ClientGeneratorConfigError, loadClientGeneratorConfig } from '../config.js';
+import { createNodeFileSystemAdapter, toPosixPath } from '../file-system.js';
+import { checkClientGeneration, planClientGeneration, runClientGeneration } from '../generate.js';
+import { parseCommandLineArguments, readFlagOption, readStringOption } from './arguments.js';
+export const CLI_USAGE = [
+    'Usage: netsuite-api <command> [options]',
+    '',
+    'Commands:',
+    '  generate        Read the controllers and the app file; write the client module, the scripts map and the copied type files.',
+    '  check           Exit non-zero when a generated file is missing or out of date.',
+    '  help            Show this message.',
+    '',
+    'Options:',
+    '  --config <path>       Config file (default: netsuite-api.config.json in the working directory).',
+    '  --dry-run             With generate: print the client module that would be written without writing anything.',
+].join('\n');
+export const EXIT_SUCCESS = 0;
+export const EXIT_PROBLEMS = 1;
+export const EXIT_USAGE = 2;
+const commands = ['generate', 'check'];
+function formatProblems(plan) {
+    return plan.problems.map((problem) => ` - ${problem.filePath}: ${problem.message}`);
+}
+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'}`);
+}
+/** Runs the CLI and resolves to the process exit code. Never throws for user errors. */
+export function runCli(argv, environment) {
+    const parsed = parseCommandLineArguments(argv);
+    const fileSystem = environment.fileSystem ?? createNodeFileSystemAdapter();
+    const command = parsed.command ?? 'help';
+    if (command === 'help' || readFlagOption(parsed.options, 'help')) {
+        environment.stdout(CLI_USAGE);
+        return EXIT_SUCCESS;
+    }
+    if (!commands.includes(command)) {
+        environment.stderr(`Unknown command '${command}'.\n\n${CLI_USAGE}`);
+        return EXIT_USAGE;
+    }
+    let config;
+    try {
+        config = loadClientGeneratorConfig(fileSystem, environment.cwd, readStringOption(parsed.options, 'config'));
+    }
+    catch (error) {
+        environment.stderr(error instanceof ClientGeneratorConfigError ? error.message : `Could not load the config: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT_USAGE;
+    }
+    const options = { config, fileSystem };
+    const failure = (plan) => {
+        environment.stderr(['The controllers cannot be turned into a client module:', ...formatProblems(plan)].join('\n'));
+        return EXIT_PROBLEMS;
+    };
+    if (command === 'generate') {
+        if (readFlagOption(parsed.options, 'dry-run')) {
+            const plan = planClientGeneration(options);
+            if (plan.problems.length > 0)
+                return failure(plan);
+            environment.stdout(plan.files[0].content);
+            return EXIT_SUCCESS;
+        }
+        const result = runClientGeneration(options);
+        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.`,
+            ...describeControllers(result),
+            ...result.writtenFiles.map((filePath) => ` - wrote ${relativeTo(environment.cwd, filePath)}`),
+        ].join('\n'));
+        return EXIT_SUCCESS;
+    }
+    const check = checkClientGeneration(options);
+    if (check.problems.length > 0)
+        return failure(check);
+    if (check.missingFiles.length > 0 || check.staleFiles.length > 0) {
+        environment.stderr([
+            'The generated files are not up to date. Run `netsuite-api generate`.',
+            ...check.missingFiles.map((filePath) => ` - missing: ${relativeTo(environment.cwd, filePath)}`),
+            ...check.staleFiles.map((filePath) => ` - out of date: ${relativeTo(environment.cwd, filePath)}`),
+        ].join('\n'));
+        return EXIT_PROBLEMS;
+    }
+    environment.stdout([`Generated files are up to date (${check.files.length} file(s)).`, ...describeControllers(check)].join('\n'));
+    return EXIT_SUCCESS;
+}

package/dist-tooling/config.d.ts

@@ -0,0 +1,43 @@
+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.
+ */
+export interface ClientGeneratorConfig {
+    /** Directory holding the controllers: one `<name>Controller.ts` per script. */
+    controllers: string;
+    /** The file declaring `app` (and any other id no controller or model owns), copied into the client module verbatim. */
+    appFile: string;
+    /** The generated client module: every wire shape, every endpoint type, one client per browser-facing controller. */
+    outFile: string;
+    /** The generated copy of the app file for the client, outside the api folder so pages and components may import it. */
+    appOutFile: string;
+    /** The generated server-side `scripts` map: what a repository passes to createSuiteletClient. */
+    scriptsOutFile: string;
+    /** The specifier the client module imports `createApiClient` from. */
+    clientModule: string;
+    /** The specifier the scripts map imports `ScriptRef` from. */
+    wireModule: string;
+    /**
+     * Type imports a controller may carry into the client module, as the specifier written in the
+     * controller mapped to the specifier the client resolves: the generated entity types, and the
+     * package's server entry mapped to its client entry (for `RawResponse`). A type imported from any
+     * other module is an error, because the client could not resolve it.
+     */
+    typeImports: Record<string, string>;
+    /** Files copied into the client as they are, source to destination: the generated entity types the carried imports point at. */
+    copyFiles: Record<string, string>;
+}
+export interface ResolvedClientGeneratorConfig extends ClientGeneratorConfig {
+    /** The config file's directory, or the working directory when no config file exists and the defaults apply. */
+    rootDirectory: string;
+}
+export declare const DEFAULT_CONFIG_FILE_NAME = "netsuite-api.config.json";
+export declare const defaultClientGeneratorConfig: ClientGeneratorConfig;
+export declare class ClientGeneratorConfigError extends Error {
+    readonly configPath: string;
+    readonly problems: string[];
+    constructor(configPath: string, problems: 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

@@ -0,0 +1,77 @@
+import * as nodePath from 'node:path';
+export const DEFAULT_CONFIG_FILE_NAME = 'netsuite-api.config.json';
+export const defaultClientGeneratorConfig = {
+    controllers: 'api/src/controllers',
+    appFile: 'netsuite.ts',
+    outFile: 'client/src/api/index.gen.ts',
+    appOutFile: 'client/src/app.gen.ts',
+    scriptsOutFile: 'api/src/scripts.gen.ts',
+    clientModule: '@amerilux/netsuite-api/client',
+    wireModule: '@amerilux/netsuite-api',
+    typeImports: { '../types/models.gen': './models.gen', '@amerilux/netsuite-api/server': '@amerilux/netsuite-api/client' },
+    copyFiles: { 'api/src/types/models.gen.ts': 'client/src/api/models.gen.ts' },
+};
+export class ClientGeneratorConfigError extends Error {
+    configPath;
+    problems;
+    constructor(configPath, problems) {
+        super(`Config '${configPath}' is invalid:\n - ${problems.join('\n - ')}`);
+        this.configPath = configPath;
+        this.problems = problems;
+        this.name = 'ClientGeneratorConfigError';
+    }
+}
+const stringSettings = ['controllers', 'appFile', 'outFile', 'appOutFile', 'scriptsOutFile', 'clientModule', 'wireModule'];
+const mapSettings = ['typeImports', 'copyFiles'];
+function isStringMap(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === 'string' && entry !== '');
+}
+function validateClientGeneratorConfig(raw, configPath) {
+    const problems = [];
+    const config = { ...defaultClientGeneratorConfig, typeImports: { ...defaultClientGeneratorConfig.typeImports }, copyFiles: { ...defaultClientGeneratorConfig.copyFiles } };
+    for (const setting of stringSettings) {
+        const value = raw[setting];
+        if (value === undefined)
+            continue;
+        if (typeof value === 'string' && value.trim() !== '')
+            config[setting] = value;
+        else
+            problems.push(`'${setting}' must be a non-empty string.`);
+    }
+    for (const setting of mapSettings) {
+        const value = raw[setting];
+        if (value === undefined)
+            continue;
+        if (isStringMap(value))
+            config[setting] = value;
+        else
+            problems.push(`'${setting}' must be an object of strings.`);
+    }
+    const known = new Set([...stringSettings, ...mapSettings]);
+    for (const key of Object.keys(raw)) {
+        if (!known.has(key))
+            problems.push(`'${key}' is not a setting.`);
+    }
+    if (problems.length > 0)
+        throw new ClientGeneratorConfigError(configPath, problems);
+    return config;
+}
+/** Loads the config in the working directory (or the one named), applying the defaults for what it omits. */
+export function loadClientGeneratorConfig(fileSystem, cwd, configPath) {
+    const resolvedConfigPath = nodePath.resolve(cwd, configPath ?? DEFAULT_CONFIG_FILE_NAME);
+    if (!fileSystem.fileExists(resolvedConfigPath)) {
+        if (configPath !== undefined)
+            throw new ClientGeneratorConfigError(resolvedConfigPath, ['the file does not exist.']);
+        return { ...defaultClientGeneratorConfig, rootDirectory: cwd };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fileSystem.readTextFile(resolvedConfigPath));
+    }
+    catch (error) {
+        throw new ClientGeneratorConfigError(resolvedConfigPath, [`not valid JSON: ${error instanceof Error ? error.message : String(error)}`]);
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new ClientGeneratorConfigError(resolvedConfigPath, ['must be a JSON object.']);
+    return { ...validateClientGeneratorConfig(raw, resolvedConfigPath), rootDirectory: nodePath.dirname(resolvedConfigPath) };
+}

package/dist-tooling/controllerReader.d.ts

@@ -0,0 +1,68 @@
+import ts from 'typescript';
+/**
+ * Reads what a controller puts on the wire, from its source alone: the script it declares in its
+ * 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 carried modules or from another controller, and the script ids are string literals.
+ */
+export interface ControllerProblem {
+    filePath: string;
+    message: string;
+}
+export interface EndpointSignature {
+    name: string;
+    /** The handler's parameter type, or undefined when the handler takes no request. */
+    requestType?: string;
+    requestOptional: boolean;
+    responseType: string;
+    /** True when the return type is written `RawResponse`: the endpoint answers with a document, and the client resolves it to a Blob. */
+    raw: boolean;
+    jsDoc?: string;
+}
+/** The return type a handler writes, exactly, to answer with a document instead of the envelope. */
+export declare const RAW_RESPONSE_TYPE_NAME = "RawResponse";
+export interface CarriedTypeImport {
+    /** The specifier as the client resolves it, after the typeImports mapping. */
+    moduleSpecifier: string;
+    names: string[];
+}
+export interface TypeDeclaration {
+    name: string;
+    /** The declaration as written, JSDoc included. */
+    text: string;
+}
+export type ControllerKind = 'restlet' | 'suitelet';
+/** The script a controller declares, as read off its entry point. */
+export interface DeclaredScript {
+    kind: ControllerKind;
+    scriptId: string;
+    deployId: string;
+    browser: boolean;
+}
+export interface ControllerContract {
+    /** The controller's name: `user` for userController.ts, matching `name` in its declaration. */
+    name: string;
+    filePath: string;
+    /** `UserEndpoints`: the type the generated module declares for the controller. */
+    endpointsTypeName: string;
+    /** `userApi`: the client the generated module exports for a browser-facing controller. */
+    clientName: string;
+    script: DeclaredScript;
+    typeImports: CarriedTypeImport[];
+    typeDeclarations: TypeDeclaration[];
+    endpoints: EndpointSignature[];
+}
+export interface ReadControllerOptions {
+    /** Type imports a controller may carry: the specifier written in the controller mapped to the specifier the client resolves. */
+    typeImports: Record<string, string>;
+}
+export interface ControllerReadResult {
+    contract?: ControllerContract;
+    problems: ControllerProblem[];
+}
+export declare function isControllerFileName(fileName: string): boolean;
+export declare function toPascalCase(name: string): string;
+/** 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;
+export declare function readControllerContract(filePath: string, source: string, options: ReadControllerOptions): ControllerReadResult;