@amerilux/netsuite-api 0.1.0 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@ The API layer for a NetSuite single-page app. The app's server side is SuiteScri
 - **`@amerilux/netsuite-api/server`**: declare a controller's endpoints and the script that serves them, expose them as a Restlet or a Suitelet, reject a call with an `ApiError`, call another Suitelet controller from server code, and find a File Cabinet file by name.
 - **`@amerilux/netsuite-api/client`**: a typed browser client per controller, built from the endpoint types.
 - **`@amerilux/netsuite-api/testing`**: stubs for the `N/*` modules and the vitest wiring that routes imports to them.
-- **`netsuite-api generate`**: reads the controllers and writes the client's whole view of the backend, one client module and one copy of the entity types, plus the server-side map of scripts. The client never imports from the server tree.
+- **`netsuite-api generate`**: reads the controllers and writes the client's whole view of the backend, one module per controller and an index re-exporting them, plus the server-side map of scripts. The client never imports from the server tree.
 - **`@amerilux/netsuite-api`** (the root): the wire itself. The envelope, the endpoint types, `ScriptDeclaration`, `ScriptRef`.
 
 The layout it assumes is the one `create-netsuite-project` scaffolds: `api/` (SuiteScript) and `client/` (React) as workspaces, and `netsuite.ts` at the root holding the application's names.
@@ -24,7 +24,7 @@ import { defineEndpoints, defineRestlet } from '@amerilux/netsuite-api/server';
 import type { Customer } from '../types/models.gen';
 import { findCustomer, searchCustomers } from '../services/customerService';
 
-export interface CustomerSearchRequest {
+export interface SearchRequest {
     search: string;
 }
 
@@ -32,7 +32,7 @@ export type CustomerSummary = Pick<Customer, 'id' | 'companyName'>;
 
 export const customerEndpoints = defineEndpoints({
     /** Customers whose name contains the search text. */
-    search: (request: CustomerSearchRequest): CustomerSummary[] => searchCustomers(request.search),
+    search: (request: SearchRequest): CustomerSummary[] => searchCustomers(request.search),
     byId: (request: { id: number }): Customer => findCustomer(request.id),
 });
 
@@ -53,46 +53,60 @@ The generator reads the file as source, so a few things are rules rather than co
 
 - Handlers are written inline with their parameter and return types annotated. A reference to a service function carries no types the generator can read.
 - Every type in the file is a wire shape and is exported.
-- A type is imported only from the carried modules (the generated entity types, by default) or from another controller. A service's return type is never used as a DTO by reference.
+- A type is imported only from the inlined files (the generated entity types, by default), the carried modules (the package's server entry, for `RawResponse`) or another controller. A service's return type is never used as a DTO by reference.
 - The script declaration is an object literal with literal ids, its `name` is the file name without `Controller`, and the entry point export and the `@NScriptType` header agree with the define function.
-- Type names and script ids are unique across controllers.
+- Script ids are unique across controllers, and no wire shape is named `Endpoints`. A shape's name carries no controller prefix: each controller's generated module is its own namespace.
 
 ## What the generator writes
 
-`netsuite-api generate`, run from the project root, writes four things:
+`netsuite-api generate`, run from the project root, writes four kinds of file:
 
-**`client/src/api/index.gen.ts`**, the client's view of the backend. For every controller its wire shapes and endpoint type, and for every browser-facing controller a client built from the declared script:
+**`client/src/api/<name>.gen.ts`**, one module per controller: the entity types it names (copied in, with whatever they refer to, so the module stands on its own), its wire shapes, its endpoint type and, for a browser-facing controller, a client built from the declared script:
 
 ```ts
+// client/src/api/customer.gen.ts
 import { createApiClient } from '@amerilux/netsuite-api/client';
-import type { Customer } from './models.gen';
 
-// customer (api/src/controllers/customerController.ts)
+// Entity types from api/src/types/models.gen.ts, copied so this module stands on its own.
 
-export interface CustomerSearchRequest {
+export interface Customer {
+    id: number;
+    companyName: string;
+}
+
+export interface SearchRequest {
     search: string;
 }
 
 export type CustomerSummary = Pick<Customer, 'id' | 'companyName'>;
 
-export type CustomerEndpoints = {
+/** The endpoint signatures of the customer controller, as its handlers declare them. */
+export type Endpoints = {
     /** Customers whose name contains the search text. */
-    search: (request: CustomerSearchRequest) => CustomerSummary[];
+    search: (request: SearchRequest) => CustomerSummary[];
     byId: (request: { id: number }) => Customer;
 };
 
-export const customerApi = createApiClient<CustomerEndpoints>({ kind: 'restlet', scriptId: 'customscript_app_customer', deployId: 'customdeploy_app_customer' });
+/** One typed function per endpoint of the customer controller: \`customer.api.search(...)\`. */
+export const api = createApiClient<Endpoints>({ kind: 'restlet', scriptId: 'customscript_app_customer', deployId: 'customdeploy_app_customer' });
 ```
 
-A hook calls `customerApi.search({ search: 'acme' })` and gets a `Promise<CustomerSummary[]>`. The second argument carries an `AbortSignal`.
+A type imported from another controller becomes an import of that controller's module. A type built on something the entity file imports itself (`CustomerCreate`, `CustomerPatch`: the repository package's input types) is an error, because the client could not carry it; write the wire shape out in the controller instead. A generated module no controller owns any more is deleted on the next run.
+
+**`client/src/api/index.gen.ts`**, the client's view of the backend: every controller's module re-exported under the controller's name.
+
+```ts
+export * as customer from './customer.gen';
+export * as user from './user.gen';
+```
 
-**`client/src/api/models.gen.ts`**, a copy of the api's generated entity types, so the carried imports resolve.
+A hook imports `{ customer }` from it, calls `customer.api.search({ search: 'acme' })` and gets a `Promise<customer.CustomerSummary[]>`. The second argument carries an `AbortSignal`.
 
 **`client/src/app.gen.ts`**, a verbatim copy of the app file, outside the api folder so a page or a component may import `app` without touching a client.
 
 **`api/src/scripts.gen.ts`**, the server-side map of every declared script by controller name. A repository passes an entry to `createSuiteletClient`; nothing else needs it.
 
-`netsuite-api check` exits non-zero when any generated file is missing or out of date, for CI. `netsuite-api generate --dry-run` prints the client module instead of writing anything.
+`netsuite-api check` exits non-zero when any generated file is missing, out of date or left over, for CI. `netsuite-api generate --dry-run` prints every file instead of writing anything.
 
 ### The app file
 
@@ -106,17 +120,17 @@ A hook calls `customerApi.search({ search: 'acme' })` and gets a `Promise<Custom
 {
   "controllers": "api/src/controllers",
   "appFile": "netsuite.ts",
-  "outFile": "client/src/api/index.gen.ts",
+  "outDir": "client/src/api",
   "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" }
+  "typeImports": { "@amerilux/netsuite-api/server": "@amerilux/netsuite-api/client" },
+  "inlineTypes": { "../types/models.gen": "api/src/types/models.gen.ts" }
 }
 ```
 
-Paths are relative to the config file. `typeImports` maps a specifier as written in a controller to the specifier the client resolves; only listed specifiers may be imported for types (the package's server entry maps to its client entry so `RawResponse` carries over). `copyFiles` copies the files those specifiers point at.
+Paths are relative to the config file. `outDir` holds the controller modules and the index, and nothing else. `inlineTypes` maps a specifier as written in a controller to the type-only file whose declarations are copied into the module of every controller importing from it. `typeImports` maps a specifier to the one the client resolves, for a type that stays an import (the package's server entry maps to its client entry so `RawResponse` carries over). A type imported from any other module is an error.
 
 ## The client at runtime
 
@@ -128,7 +142,13 @@ import { configureApiClient } from '@amerilux/netsuite-api/client';
 if (import.meta.env.DEV) configureApiClient({ basePaths: { restlet: '/api/restlet', suitelet: '/api/suitelet' } });
 ```
 
-A failed call rejects with an `ApiClientError` carrying the envelope's status and message.
+A failed call rejects with an `ApiClientError` carrying the envelope's status and message; a call that got no answer at all carries `NO_RESPONSE_STATUS` (0). Before it rejects, the failure goes to the handler `configureApiClient` was given, with the script, the endpoint and the request, so the app reports every failure in one place and a hook carries no error handling of its own:
+
+```ts
+configureApiClient({ onError: (error, { endpoint }) => showBanner(`${endpoint}: ${error.message}`) });
+```
+
+The rejection still reaches the caller, so a query sees its error state. A call that reports the failure itself passes `{ handleError: false }` as its second argument; an aborted call is not a failure and never reaches the handler.
 
 ## Authorizing calls
 
@@ -163,7 +183,7 @@ export const documentsEndpoints = defineEndpoints({
 });
 ```
 
-In the browser, `documentsApi.csv({ month })` resolves to a `Blob`; hand it to `URL.createObjectURL` for a download link. A text answer takes a content type, a body, optional headers and, for a download, a file name; a file answer takes an `N/file` object and whether to show it inline. A failure still arrives as the envelope and is thrown as an `ApiClientError`. A Restlet cannot write a raw answer: a handler returning one there is a 500.
+In the browser, `documents.api.csv({ month })` resolves to a `Blob`; hand it to `URL.createObjectURL` for a download link. A text answer takes a content type, a body, optional headers and, for a download, a file name; a file answer takes an `N/file` object and whether to show it inline. A failure still arrives as the envelope and is thrown as an `ApiClientError`. A Restlet cannot write a raw answer: a handler returning one there is a 500.
 
 ## Calling a Suitelet from server code
 

package/dist/client/apiClient.d.ts

@@ -4,15 +4,34 @@ import { type EndpointRequest, type EndpointResponse, type Endpoints, type RawRe
  * `kind` decides the URL, so a controller can move between Restlet and Suitelet without touching
  * the caller. In the deployed app the call rides the NetSuite session on the same origin; a
  * development server that proxies to a sandbox sets its own base paths with configureApiClient.
+ *
+ * Every failure is one error type, ApiClientError, and is handed to the configured error handler
+ * before the call rejects: the app reports failures in one place, and a hook or a page adds error
+ * handling only when it wants something other than the default.
  */
 export interface ApiCallOptions {
     signal?: AbortSignal;
+    /**
+     * Whether the configured error handler is told when this call fails. True unless set: a caller
+     * that reports the failure itself (a form showing it inline) passes false. The call rejects either way.
+     */
+    handleError?: boolean;
 }
+/** The status of an ApiClientError for a call that got no answer at all: the network, not the script, failed. */
+export declare const NO_RESPONSE_STATUS = 0;
 export declare class ApiClientError extends Error {
     readonly status: number;
     readonly details?: unknown | undefined;
     constructor(status: number, message: string, details?: unknown | undefined);
 }
+/** What the error handler is told about the call that failed. */
+export interface ApiCallContext {
+    scriptRef: ScriptRef;
+    endpoint: string;
+    request: unknown;
+}
+/** Runs for a failed call before it rejects. It reports; it does not recover, and it must not throw. */
+export type ApiErrorHandler = (error: ApiClientError, context: ApiCallContext) => void;
 /** The path each script kind is served from, without the script and deploy query parameters. */
 export type ApiBasePaths = Record<ScriptKind, string>;
 /** Where NetSuite serves Restlets and Suitelets on the account's own origin. */
@@ -20,10 +39,18 @@ export declare const NETSUITE_API_BASE_PATHS: ApiBasePaths;
 export interface ApiClientConfiguration {
     /** Base paths to use instead of NetSuite's own, e.g. the routes of a local development proxy. */
     basePaths?: Partial<ApiBasePaths>;
+    /**
+     * Told about every failed call, unless the call passed `handleError: false`, before the call
+     * rejects. The rejection still reaches the caller (a query sees its error state), so the handler
+     * is where the app reports: a banner, a log, a redirect on 401. An aborted call is not a failure
+     * and never reaches it.
+     */
+    onError?: ApiErrorHandler;
 }
 /**
- * Sets where calls go. Call it once at startup, before the first call; a client built earlier picks
- * the change up because the URL is built per call. Without a call, NetSuite's own paths apply.
+ * Sets where calls go and who hears about failures. Call it once at startup, before the first call;
+ * a client built earlier picks the change up because both are read per call. Without a call,
+ * NetSuite's own paths apply and failures only reject.
  */
 export declare function configureApiClient(configuration: ApiClientConfiguration): void;
 export declare function buildApiUrl(scriptRef: ScriptRef): string;
@@ -38,8 +65,8 @@ export declare function callRawEndpoint(scriptRef: ScriptRef, endpointName: stri
 /** What the client resolves to for an endpoint's response type: a Blob for a raw answer, the data otherwise. */
 export type ClientResponse<TResponse> = TResponse extends RawResponse ? Blob : TResponse;
 /**
- * One function per endpoint, typed by the controller's handlers: `userApi.roles()`,
- * `ordersApi.byId({ id })`, `exportsApi.csv({ month })` resolving to a Blob. The request comes first,
+ * One function per endpoint, typed by the controller's handlers: `user.api.roles()`,
+ * `orders.api.byId({ id })`, `exports.api.csv({ month })` resolving to a Blob. The request comes first,
  * the call options second.
  */
 export type ApiClient<TEndpoints extends Endpoints> = {
@@ -50,8 +77,8 @@ export interface ApiClientOptions {
     rawEndpoints?: readonly string[];
 }
 /**
- * Builds the typed client for a controller from its script: `createApiClient<UserEndpoints>({ kind, scriptId, deployId })`.
+ * Builds the typed client for a controller from its script: `createApiClient<Endpoints>({ kind, scriptId, deployId })`.
  * The endpoint names come from the type alone; the property accessed is the endpoint named on the wire.
- * The generated client module of a project calls this once per browser-facing controller.
+ * The generated module of a browser-facing controller calls this once.
  */
 export declare function createApiClient<TEndpoints extends Endpoints>(scriptRef: ScriptRef, clientOptions?: ApiClientOptions): ApiClient<TEndpoints>;

package/dist/client/apiClient.js

@@ -1,4 +1,6 @@
 import { ENDPOINT_PARAMETER } from '../index.js';
+/** The status of an ApiClientError for a call that got no answer at all: the network, not the script, failed. */
+export const NO_RESPONSE_STATUS = 0;
 export class ApiClientError extends Error {
     constructor(status, message, details) {
         super(message);
@@ -13,17 +15,41 @@ export const NETSUITE_API_BASE_PATHS = {
     suitelet: '/app/site/hosting/scriptlet.nl',
 };
 let configuredBasePaths = NETSUITE_API_BASE_PATHS;
+let configuredErrorHandler;
 /**
- * Sets where calls go. Call it once at startup, before the first call; a client built earlier picks
- * the change up because the URL is built per call. Without a call, NetSuite's own paths apply.
+ * Sets where calls go and who hears about failures. Call it once at startup, before the first call;
+ * a client built earlier picks the change up because both are read per call. Without a call,
+ * NetSuite's own paths apply and failures only reject.
  */
 export function configureApiClient(configuration) {
     configuredBasePaths = { ...NETSUITE_API_BASE_PATHS, ...configuration.basePaths };
+    configuredErrorHandler = configuration.onError;
 }
 export function buildApiUrl(scriptRef) {
     const parameters = new URLSearchParams({ script: scriptRef.scriptId, deploy: scriptRef.deployId });
     return `${configuredBasePaths[scriptRef.kind]}?${parameters.toString()}`;
 }
+function isAbort(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+/**
+ * Runs one call: whatever fails inside becomes an ApiClientError (a fetch that never answered gets
+ * NO_RESPONSE_STATUS), goes to the configured handler unless the call opted out, and rejects. An
+ * abort is the caller's own doing and passes through untouched.
+ */
+async function reportingFailures(scriptRef, endpointName, request, options, call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (isAbort(error))
+            throw error;
+        const failure = error instanceof ApiClientError ? error : new ApiClientError(NO_RESPONSE_STATUS, `Could not reach ${scriptRef.scriptId}.${endpointName}: ${error instanceof Error ? error.message : String(error)}`, error);
+        if (options.handleError !== false)
+            configuredErrorHandler === null || configuredErrorHandler === void 0 ? void 0 : configuredErrorHandler(failure, { scriptRef, endpoint: endpointName, request });
+        throw failure;
+    }
+}
 /** The POST every call is: the request plus the endpoint name, as JSON. */
 function postEndpoint(scriptRef, endpointName, request, options) {
     return fetch(buildApiUrl(scriptRef), {
@@ -44,43 +70,47 @@ function parseEnvelope(text) {
     }
 }
 /** Calls one endpoint of a controller: a POST whose JSON body carries the request and the endpoint name. */
-export async function callEndpoint(scriptRef, endpointName, request = {}, options = {}) {
-    var _a;
-    const response = await postEndpoint(scriptRef, endpointName, request, options);
-    const text = await response.text();
-    const envelope = parseEnvelope(text);
-    if (!envelope) {
-        throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
-    }
-    if (envelope.error !== null || envelope.status >= 400) {
-        throw new ApiClientError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`);
-    }
-    return envelope.data;
+export function callEndpoint(scriptRef, endpointName, request = {}, options = {}) {
+    return reportingFailures(scriptRef, endpointName, request, options, async () => {
+        var _a;
+        const response = await postEndpoint(scriptRef, endpointName, request, options);
+        const text = await response.text();
+        const envelope = parseEnvelope(text);
+        if (!envelope) {
+            throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
+        }
+        if (envelope.error !== null || envelope.status >= 400) {
+            throw new ApiClientError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`);
+        }
+        return envelope.data;
+    });
 }
 /**
  * Calls an endpoint that answers with a document instead of the envelope (a Suitelet handler returning
  * rawResponse) and resolves to its body as a Blob. A failure still arrives as an envelope, and is
  * thrown as an ApiClientError with its status.
  */
-export async function callRawEndpoint(scriptRef, endpointName, request = {}, options = {}) {
-    var _a, _b;
-    const response = await postEndpoint(scriptRef, endpointName, request, options);
-    const contentType = (_a = response.headers.get('Content-Type')) !== null && _a !== void 0 ? _a : '';
-    if (!response.ok || contentType.includes('application/json')) {
-        const text = await response.text();
-        const envelope = parseEnvelope(text);
-        if (envelope && (envelope.error !== null || envelope.status >= 400))
-            throw new ApiClientError(envelope.status, (_b = envelope.error) !== null && _b !== void 0 ? _b : `Request failed (${envelope.status})`);
-        if (!response.ok)
-            throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
-        throw new ApiClientError(response.status, `${scriptRef.scriptId}.${endpointName} answered JSON where a document was expected.`, text.slice(0, 500));
-    }
-    return response.blob();
+export function callRawEndpoint(scriptRef, endpointName, request = {}, options = {}) {
+    return reportingFailures(scriptRef, endpointName, request, options, async () => {
+        var _a, _b;
+        const response = await postEndpoint(scriptRef, endpointName, request, options);
+        const contentType = (_a = response.headers.get('Content-Type')) !== null && _a !== void 0 ? _a : '';
+        if (!response.ok || contentType.includes('application/json')) {
+            const text = await response.text();
+            const envelope = parseEnvelope(text);
+            if (envelope && (envelope.error !== null || envelope.status >= 400))
+                throw new ApiClientError(envelope.status, (_b = envelope.error) !== null && _b !== void 0 ? _b : `Request failed (${envelope.status})`);
+            if (!response.ok)
+                throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
+            throw new ApiClientError(response.status, `${scriptRef.scriptId}.${endpointName} answered JSON where a document was expected.`, text.slice(0, 500));
+        }
+        return response.blob();
+    });
 }
 /**
- * Builds the typed client for a controller from its script: `createApiClient<UserEndpoints>({ kind, scriptId, deployId })`.
+ * Builds the typed client for a controller from its script: `createApiClient<Endpoints>({ kind, scriptId, deployId })`.
  * The endpoint names come from the type alone; the property accessed is the endpoint named on the wire.
- * The generated client module of a project calls this once per browser-facing controller.
+ * The generated module of a browser-facing controller calls this once.
  */
 export function createApiClient(scriptRef, clientOptions = {}) {
     var _a;

package/dist/client/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * The browser side of the API: a typed client per controller, built from the endpoint types the
- * generator writes into the project's client module. Runs in the browser only; nothing here imports N/*.
+ * generator writes into the project's client modules. Runs in the browser only; nothing here imports N/*.
  */
-export { ApiClientError, NETSUITE_API_BASE_PATHS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
-export type { ApiBasePaths, ApiCallOptions, ApiClient, ApiClientConfiguration, ApiClientOptions, ClientResponse } from './apiClient.js';
+export { ApiClientError, NETSUITE_API_BASE_PATHS, NO_RESPONSE_STATUS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
+export type { ApiBasePaths, ApiCallContext, ApiCallOptions, ApiClient, ApiClientConfiguration, ApiClientOptions, ApiErrorHandler, ClientResponse } from './apiClient.js';
 export { ENDPOINT_PARAMETER } from '../index.js';
 export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef } from '../index.js';

package/dist/client/index.js

@@ -1,6 +1,6 @@
 /**
  * The browser side of the API: a typed client per controller, built from the endpoint types the
- * generator writes into the project's client module. Runs in the browser only; nothing here imports N/*.
+ * generator writes into the project's client modules. Runs in the browser only; nothing here imports N/*.
  */
-export { ApiClientError, NETSUITE_API_BASE_PATHS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
+export { ApiClientError, NETSUITE_API_BASE_PATHS, NO_RESPONSE_STATUS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
 export { ENDPOINT_PARAMETER } from '../index.js';

package/dist-tooling/cli/main.js

@@ -7,13 +7,13 @@ 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.',
+    '  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.',
+    '  check           Exit non-zero when a generated file is missing, out of date or left over.',
     '  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.',
+    '  --dry-run             With generate: print every file that would be written, without writing anything.',
 ].join('\n');
 export const EXIT_SUCCESS = 0;
 export const EXIT_PROBLEMS = 1;
@@ -51,7 +51,7 @@ export function runCli(argv, environment) {
     }
     const options = { config, fileSystem };
     const failure = (plan) => {
-        environment.stderr(['The controllers cannot be turned into a client module:', ...formatProblems(plan)].join('\n'));
+        environment.stderr(['The controllers cannot be turned into client modules:', ...formatProblems(plan)].join('\n'));
         return EXIT_PROBLEMS;
     };
     if (command === 'generate') {
@@ -59,27 +59,29 @@ export function runCli(argv, environment) {
             const plan = planClientGeneration(options);
             if (plan.problems.length > 0)
                 return failure(plan);
-            environment.stdout(plan.files[0].content);
+            environment.stdout(plan.files.map((file) => `// ---- ${relativeTo(environment.cwd, file.path)}\n${file.content}`).join('\n'));
             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.`,
+            `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` : ''}.`,
             ...describeControllers(result),
             ...result.writtenFiles.map((filePath) => ` - wrote ${relativeTo(environment.cwd, filePath)}`),
+            ...result.deletedFiles.map((filePath) => ` - deleted ${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) {
+    if (check.missingFiles.length > 0 || check.staleFiles.length > 0 || check.leftoverFiles.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)}`),
+            ...check.leftoverFiles.map((filePath) => ` - left over: ${relativeTo(environment.cwd, filePath)}`),
         ].join('\n'));
         return EXIT_PROBLEMS;
     }

package/dist-tooling/config.d.ts

@@ -6,27 +6,32 @@ import type { FileSystemAdapter } from './file-system.js';
 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. */
+    /** The file declaring `app` (and any other id no controller or model owns), copied into the client verbatim. */
     appFile: string;
-    /** The generated client module: every wire shape, every endpoint type, one client per browser-facing controller. */
-    outFile: string;
+    /** 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 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. */
+    /** The specifier the controller modules import `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.
+     * Type imports a controller may carry into its generated module as imports, as the specifier
+     * written in the controller mapped to the specifier the client resolves: the package's server
+     * entry mapped to its client entry (for `RawResponse`). A type imported from any module listed
+     * in neither this nor `inlineTypes` 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>;
+    /**
+     * 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.
+     */
+    inlineTypes: 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. */

package/dist-tooling/config.js

@@ -3,13 +3,13 @@ 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',
+    outDir: 'client/src/api',
     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' },
+    typeImports: { '@amerilux/netsuite-api/server': '@amerilux/netsuite-api/client' },
+    inlineTypes: { '../types/models.gen': 'api/src/types/models.gen.ts' },
 };
 export class ClientGeneratorConfigError extends Error {
     configPath;
@@ -21,14 +21,14 @@ export class ClientGeneratorConfigError extends Error {
         this.name = 'ClientGeneratorConfigError';
     }
 }
-const stringSettings = ['controllers', 'appFile', 'outFile', 'appOutFile', 'scriptsOutFile', 'clientModule', 'wireModule'];
-const mapSettings = ['typeImports', 'copyFiles'];
+const stringSettings = ['controllers', 'appFile', 'outDir', 'appOutFile', '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 validateClientGeneratorConfig(raw, configPath) {
     const problems = [];
-    const config = { ...defaultClientGeneratorConfig, typeImports: { ...defaultClientGeneratorConfig.typeImports }, copyFiles: { ...defaultClientGeneratorConfig.copyFiles } };
+    const config = { ...defaultClientGeneratorConfig, typeImports: { ...defaultClientGeneratorConfig.typeImports }, inlineTypes: { ...defaultClientGeneratorConfig.inlineTypes } };
     for (const setting of stringSettings) {
         const value = raw[setting];
         if (value === undefined)

package/dist-tooling/controllerReader.d.ts

@@ -4,7 +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 carried modules or from another controller, and the script ids are string literals.
+ * from the inlined files, the carried modules or another controller, and the script ids are string
+ * literals.
  */
 export interface ControllerProblem {
     filePath: string;
@@ -22,10 +23,31 @@ export interface EndpointSignature {
 }
 /** The return type a handler writes, exactly, to answer with a document instead of the envelope. */
 export declare const RAW_RESPONSE_TYPE_NAME = "RawResponse";
+/** The type every generated controller module declares for its endpoint signatures: `user.Endpoints`. */
+export declare const GENERATED_ENDPOINTS_TYPE_NAME = "Endpoints";
+/** The client every generated browser-facing controller module exports: `user.api`. */
+export declare const GENERATED_CLIENT_NAME = "api";
+/** One name of a type import, `Employee` or `Employee as EmployeeRecord`. */
+export interface TypeImportName {
+    name: string;
+    alias?: string;
+}
+/** A type import the generated module keeps as an import: a package type such as RawResponse, under the specifier the client resolves. */
 export interface CarriedTypeImport {
     /** The specifier as the client resolves it, after the typeImports mapping. */
     moduleSpecifier: string;
-    names: string[];
+    names: TypeImportName[];
+}
+/** A type import whose declarations are copied into the generated module: the generated entity types. */
+export interface InlinedTypeImport {
+    /** The specifier as written in the controller: a key of inlineTypes. */
+    specifier: string;
+    names: TypeImportName[];
+}
+/** A type import from a sibling controller, resolved to that controller's generated module. */
+export interface ControllerTypeImport {
+    controllerName: string;
+    names: TypeImportName[];
 }
 export interface TypeDeclaration {
     name: string;
@@ -44,25 +66,24 @@ 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[];
+    carriedTypeImports: CarriedTypeImport[];
+    inlinedTypeImports: InlinedTypeImport[];
+    controllerTypeImports: ControllerTypeImport[];
     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. */
+    /** Type imports a controller may carry as imports: the specifier written in the controller mapped to the specifier the client resolves. */
     typeImports: Record<string, string>;
+    /** Type imports whose declarations are copied into the generated module: the specifier written in the controller mapped to the file it names. */
+    inlineTypes: 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;