@amerilux/netsuite-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AmeriLux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# @amerilux/netsuite-api
+
+The API layer for a NetSuite single-page app. The app's server side is SuiteScript; its browser side is a bundle served by a Suitelet. This package holds what sits between them, so a project writes controllers and services and nothing else:
+
+- **`@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.
+- **`@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.
+
+## A controller
+
+One file per script under `api/src/controllers/`, named `<name>Controller.ts`. The file declares the wire shapes, the endpoints, and the script that serves them:
+
+```ts
+/**
+ * @NApiVersion 2.1
+ * @NScriptType Restlet
+ * @NModuleScope SameAccount
+ */
+import { defineEndpoints, defineRestlet } from '@amerilux/netsuite-api/server';
+import type { Customer } from '../types/models.gen';
+import { findCustomer, searchCustomers } from '../services/customerService';
+
+export interface CustomerSearchRequest {
+    search: string;
+}
+
+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),
+    byId: (request: { id: number }): Customer => findCustomer(request.id),
+});
+
+export type CustomerEndpoints = typeof customerEndpoints;
+
+export const post = defineRestlet({
+    name: 'customer',
+    scriptId: 'customscript_app_customer',
+    deployId: 'customdeploy_app_customer',
+}, customerEndpoints);
+```
+
+Every call is a POST whose JSON body carries the request plus an `endpoint` property naming the endpoint. The handler answers with data, or throws an `ApiError` for a status the caller should see; anything else is a 500 with the details logged. A Suitelet controller is the same file with `defineSuitelet` and `onRequest` instead, and `browser: false` in the declaration when only server code calls it.
+
+The declaration is the controller's own statement of the script it is deployed as. It creates nothing: the controller builds, tests and bundles before any script record exists. The ids are how a client reaches the controller once it is deployed, so set them to whatever the record and deployment are called in NetSuite and in the SDF object; the generator wires every client to them.
+
+The generator reads the file as source, so a few things are rules rather than conventions. Each of them is an error with a message when broken:
+
+- 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.
+- 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.
+
+## What the generator writes
+
+`netsuite-api generate`, run from the project root, writes four things:
+
+**`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:
+
+```ts
+import { createApiClient } from '@amerilux/netsuite-api/client';
+import type { Customer } from './models.gen';
+
+// customer (api/src/controllers/customerController.ts)
+
+export interface CustomerSearchRequest {
+    search: string;
+}
+
+export type CustomerSummary = Pick<Customer, 'id' | 'companyName'>;
+
+export type CustomerEndpoints = {
+    /** Customers whose name contains the search text. */
+    search: (request: CustomerSearchRequest) => CustomerSummary[];
+    byId: (request: { id: number }) => Customer;
+};
+
+export const customerApi = createApiClient<CustomerEndpoints>({ 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`.
+
+**`client/src/api/models.gen.ts`**, a copy of the api's generated entity types, so the carried imports resolve.
+
+**`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.
+
+### The app file
+
+`netsuite.ts` at the project root holds the application's names and any id no controller or model owns. Both sides use it, so the client gets a verbatim copy: the file is exported constants and types only, with no imports and nothing that runs.
+
+### Configuration
+
+`netsuite-api.config.json` at the project root, every setting optional. The defaults:
+
+```json
+{
+  "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" }
+}
+```
+
+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.
+
+## The client at runtime
+
+Calls go to NetSuite's own Restlet and Suitelet paths on the current origin, riding the session. A development server that proxies to a sandbox sets its own paths once at startup:
+
+```ts
+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.
+
+## Authorizing calls
+
+A Restlet runs as the caller's role, and NetSuite's own permissions apply to every record the handler touches. When a controller needs a rule of its own, such as an endpoint only some roles may call, the define call takes an `authorize` hook, run before every handler once the endpoint is known to exist:
+
+```ts
+import * as runtime from 'N/runtime';
+import { ApiError, defineEndpoints, defineRestlet } from '@amerilux/netsuite-api/server';
+
+const ADMINISTRATOR = 3;
+
+export const post = defineRestlet({ name: 'orders', scriptId: '...', deployId: '...' }, ordersEndpoints, {
+    authorize: ({ endpoint }) => {
+        if (endpoint === 'remove' && Number(runtime.getCurrentUser().role) !== ADMINISTRATOR) throw ApiError.forbidden('Only an administrator removes orders.');
+    },
+});
+```
+
+The hook sees the controller, the endpoint name and the request. Throwing an `ApiError` answers with its status and message; returning lets the call through. Reading the session belongs in a repository function in a project that keeps to its layers, so a real hook calls one.
+
+## Answering with a document
+
+Every endpoint answers with the JSON envelope, except a Suitelet endpoint that returns `rawResponse(...)`: a CSV export, a rendered PDF, a File Cabinet file. The handler writes `RawResponse` as its return type, exactly, and the generator lists the endpoint on the client, which resolves it to a `Blob`:
+
+```ts
+import type { RawResponse } from '@amerilux/netsuite-api/server';
+import { defineEndpoints, defineSuitelet, rawResponse } from '@amerilux/netsuite-api/server';
+
+export const documentsEndpoints = defineEndpoints({
+    csv: (request: { month: string }): RawResponse => rawResponse({ contentType: 'text/csv', body: buildCsv(request.month), fileName: `orders-${request.month}.csv` }),
+    invoicePdf: (request: { id: number }): RawResponse => rawResponse({ file: renderInvoice(request.id), inline: true }),
+});
+```
+
+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.
+
+## Calling a Suitelet from server code
+
+A Restlet runs as the caller's role. When a lookup needs a role the caller lacks, put it behind a Suitelet deployed to run as that role, declare it `browser: false`, and call it from a repository through the generated scripts map:
+
+```ts
+import { createSuiteletClient } from '@amerilux/netsuite-api/server';
+import type { UserRolesEndpoints } from '../controllers/userRolesController';
+import { scripts } from '../scripts.gen';
+
+const userRolesApi = createSuiteletClient<UserRolesEndpoints>(scripts.userRoles);
+export const listRolesForEmployee = (employeeId: number) => userRolesApi.byEmployee({ employeeId }).roles;
+```
+
+## Tests
+
+`N/*` modules exist only inside NetSuite. The `testing` entry ships a stub per module, each export a `vi.fn()`, and the vitest wiring:
+
+```ts
+import { inlinedPackagesForNetsuiteStubs, netsuiteModuleStubAliases } from '@amerilux/netsuite-api/testing';
+
+export default defineConfig({
+    resolve: { alias: [...netsuiteModuleStubAliases()] },
+    test: { server: { deps: { inline: [...inlinedPackagesForNetsuiteStubs] } } },
+});
+```
+
+Inlining matters: vitest leaves node_modules to Node's resolver by default, and Node knows no `N/log`. With the package inlined, its own `N/*` imports go through the alias too.
+
+## Development
+
+```
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+Tag `v<version>` matching `package.json` to publish.
+
+## License
+
+MIT

package/dist/client/apiClient.d.ts

@@ -0,0 +1,57 @@
+import { type EndpointRequest, type EndpointResponse, type Endpoints, type RawResponse, type ScriptKind, type ScriptRef } from '../index.js';
+/**
+ * Calls an API controller by its script and deployment ids, one endpoint at a time. The entry's
+ * `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.
+ */
+export interface ApiCallOptions {
+    signal?: AbortSignal;
+}
+export declare class ApiClientError extends Error {
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(status: number, message: string, details?: unknown | undefined);
+}
+/** 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. */
+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>;
+}
+/**
+ * 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.
+ */
+export declare function configureApiClient(configuration: ApiClientConfiguration): void;
+export declare function buildApiUrl(scriptRef: ScriptRef): string;
+/** Calls one endpoint of a controller: a POST whose JSON body carries the request and the endpoint name. */
+export declare function callEndpoint<TData>(scriptRef: ScriptRef, endpointName: string, request?: object, options?: ApiCallOptions): Promise<TData>;
+/**
+ * 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 declare function callRawEndpoint(scriptRef: ScriptRef, endpointName: string, request?: object, options?: ApiCallOptions): Promise<Blob>;
+/** 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,
+ * the call options second.
+ */
+export type ApiClient<TEndpoints extends Endpoints> = {
+    readonly [TName in keyof TEndpoints]: (request: EndpointRequest<TEndpoints[TName]>, options?: ApiCallOptions) => Promise<ClientResponse<EndpointResponse<TEndpoints[TName]>>>;
+};
+export interface ApiClientOptions {
+    /** The endpoints that answer with a document: the generator lists every handler whose return type is RawResponse. */
+    rawEndpoints?: readonly string[];
+}
+/**
+ * Builds the typed client for a controller from its script: `createApiClient<UserEndpoints>({ 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.
+ */
+export declare function createApiClient<TEndpoints extends Endpoints>(scriptRef: ScriptRef, clientOptions?: ApiClientOptions): ApiClient<TEndpoints>;

package/dist/client/apiClient.js

@@ -0,0 +1,96 @@
+import { ENDPOINT_PARAMETER } from '../index.js';
+export class ApiClientError extends Error {
+    constructor(status, message, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.name = 'ApiClientError';
+    }
+}
+/** Where NetSuite serves Restlets and Suitelets on the account's own origin. */
+export const NETSUITE_API_BASE_PATHS = {
+    restlet: '/app/site/hosting/restlet.nl',
+    suitelet: '/app/site/hosting/scriptlet.nl',
+};
+let configuredBasePaths = NETSUITE_API_BASE_PATHS;
+/**
+ * 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.
+ */
+export function configureApiClient(configuration) {
+    configuredBasePaths = { ...NETSUITE_API_BASE_PATHS, ...configuration.basePaths };
+}
+export function buildApiUrl(scriptRef) {
+    const parameters = new URLSearchParams({ script: scriptRef.scriptId, deploy: scriptRef.deployId });
+    return `${configuredBasePaths[scriptRef.kind]}?${parameters.toString()}`;
+}
+/** The POST every call is: the request plus the endpoint name, as JSON. */
+function postEndpoint(scriptRef, endpointName, request, options) {
+    return fetch(buildApiUrl(scriptRef), {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ ...request, [ENDPOINT_PARAMETER]: endpointName }),
+        signal: options.signal,
+    });
+}
+function parseEnvelope(text) {
+    try {
+        const parsed = text ? JSON.parse(text) : undefined;
+        return parsed && typeof parsed === 'object' && 'status' in parsed ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 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;
+}
+/**
+ * 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();
+}
+/**
+ * Builds the typed client for a controller from its script: `createApiClient<UserEndpoints>({ 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.
+ */
+export function createApiClient(scriptRef, clientOptions = {}) {
+    var _a;
+    const rawEndpoints = new Set((_a = clientOptions.rawEndpoints) !== null && _a !== void 0 ? _a : []);
+    return new Proxy({}, {
+        get(_target, endpointName) {
+            if (typeof endpointName !== 'string')
+                return undefined;
+            const call = rawEndpoints.has(endpointName) ? callRawEndpoint : callEndpoint;
+            return (request, options) => call(scriptRef, endpointName, (request !== null && request !== void 0 ? request : {}), options);
+        },
+    });
+}

package/dist/client/index.d.ts

@@ -0,0 +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/*.
+ */
+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 { 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

@@ -0,0 +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/*.
+ */
+export { ApiClientError, NETSUITE_API_BASE_PATHS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
+export { ENDPOINT_PARAMETER } from '../index.js';

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The wire: what a controller answers with, how a call names its endpoint, and how a script is
+ * reached. Both sides import this module; nothing in it touches NetSuite or the browser.
+ */
+/** Every controller answers with this envelope; `data` is null whenever `error` is set. */
+export interface ApiEnvelope<TData> {
+    status: number;
+    error: string | null;
+    data: TData | null;
+}
+/** The body of a failed call, as thrown by the client's ApiClientError. */
+export interface ApiErrorBody {
+    status: number;
+    error: string;
+    details?: unknown;
+}
+/**
+ * Every call is a POST whose JSON body carries the request plus this property, naming which endpoint
+ * of the controller the call is for.
+ */
+export declare const ENDPOINT_PARAMETER = "endpoint";
+/**
+ * An endpoint as the controller declares it: a synchronous function from a request to a response.
+ * The parameter type is the request shape and the return type the response shape; a handler with no
+ * parameter takes no request. The clients derive their call signatures from these types.
+ */
+export type Endpoint = (request: never) => unknown;
+/** A controller's endpoints by name: `typeof userEndpoints`, the type the clients are built from. */
+export type Endpoints = Record<string, Endpoint>;
+/** The request type of an endpoint, or void when its handler takes no parameter. */
+export type EndpointRequest<TEndpoint extends Endpoint> = Parameters<TEndpoint> extends [] ? void : Parameters<TEndpoint>[0];
+/** The response type of an endpoint: what its handler returns. */
+export type EndpointResponse<TEndpoint extends Endpoint> = ReturnType<TEndpoint>;
+/**
+ * What a Suitelet endpoint returns to answer with something other than the JSON envelope: a file
+ * download, a CSV, a rendered PDF. The server builds one with rawResponse(); the browser client
+ * resolves such an endpoint to a Blob. A Restlet cannot answer with one. A handler that answers this
+ * way writes `RawResponse` as its return type, exactly, so the generator can tell the client.
+ */
+export interface RawResponse {
+    readonly isRawResponse: true;
+}
+/** How a script is reached over HTTP; the client builds the URL from it. */
+export type ScriptKind = 'restlet' | 'suitelet';
+/**
+ * What a controller declares about the script that serves it, passed to defineRestlet or
+ * defineSuitelet. Nothing here creates or deploys anything: the controller builds, tests and bundles
+ * before a script record exists. The ids are how a client reaches the controller once it is deployed,
+ * so they are set to whatever the script record and its deployment are called in NetSuite (and in
+ * the SDF object under netsuite/Objects); the generator wires every client to them as long as they
+ * match.
+ */
+export interface ScriptDeclaration {
+    /** The controller's name, as the logs and the generated clients call it: `user` for userController.ts. */
+    name: string;
+    /**
+     * The script record's id, `customscript_<prefix>_<name>`. Change it freely to match the record in
+     * NetSuite; the generated clients follow.
+     */
+    scriptId: string;
+    /** The deployment's id, `customdeploy_<prefix>_<name>`, with the same freedom as scriptId. */
+    deployId: string;
+    /**
+     * False when only server code calls the script (a Suitelet deployed to run as another role, called
+     * through the Suitelet client). The generator then emits the controller's types but no browser
+     * client. Defaults to true.
+     */
+    browser?: boolean;
+}
+/** One deployed script as a client reaches it: the declaration plus how it is served. */
+export interface ScriptRef {
+    kind: ScriptKind;
+    scriptId: string;
+    deployId: string;
+    browser?: boolean;
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * The wire: what a controller answers with, how a call names its endpoint, and how a script is
+ * reached. Both sides import this module; nothing in it touches NetSuite or the browser.
+ */
+/**
+ * Every call is a POST whose JSON body carries the request plus this property, naming which endpoint
+ * of the controller the call is for.
+ */
+export const ENDPOINT_PARAMETER = 'endpoint';

package/dist/server/apiError.d.ts

@@ -0,0 +1,9 @@
+/** Thrown by domain code or handlers; the controller wrapper turns it into the envelope's status and error. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(status: number, message: string, details?: unknown | undefined);
+    static badRequest(message: string, details?: unknown): ApiError;
+    static notFound(message: string, details?: unknown): ApiError;
+    static forbidden(message?: string): ApiError;
+}

package/dist/server/apiError.js

@@ -0,0 +1,18 @@
+/** Thrown by domain code or handlers; the controller wrapper turns it into the envelope's status and error. */
+export class ApiError extends Error {
+    constructor(status, message, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.name = 'ApiError';
+    }
+    static badRequest(message, details) {
+        return new ApiError(400, message, details);
+    }
+    static notFound(message, details) {
+        return new ApiError(404, message, details);
+    }
+    static forbidden(message = 'Not permitted') {
+        return new ApiError(403, message);
+    }
+}

package/dist/server/defineRestlet.d.ts

@@ -0,0 +1,15 @@
+import type { ApiEnvelope, Endpoints, ScriptDeclaration } from '../index.js';
+import { type ControllerOptions } from './endpoint.js';
+/**
+ * Exposes a controller's endpoints as a Restlet:
+ *
+ *     export const post = defineRestlet({ name: 'user', scriptId: 'customscript_app_user', deployId: 'customdeploy_app_user' }, userEndpoints);
+ *
+ * Every call is a POST whose JSON body names the endpoint, so `post` is the only entry point a
+ * controller exports. The declaration names the script the controller is deployed as; the generator
+ * reads it from this call to build the clients. The options carry the authorize hook, run before
+ * every handler. A Restlet always answers with the JSON envelope; an endpoint that returns a raw
+ * response belongs in a Suitelet.
+ */
+export type RestletEntryPoint = (requestBody: unknown) => ApiEnvelope<unknown>;
+export declare function defineRestlet(script: ScriptDeclaration, endpoints: Endpoints, options?: ControllerOptions): RestletEntryPoint;

package/dist/server/defineRestlet.js

@@ -0,0 +1,4 @@
+import { invokeEndpoint } from './endpoint.js';
+export function defineRestlet(script, endpoints, options = {}) {
+    return (requestBody) => invokeEndpoint(script.name, endpoints, requestBody, { ...options, allowRawResponse: false }).envelope;
+}

package/dist/server/defineSuitelet.d.ts

@@ -0,0 +1,16 @@
+import type { EntryPoints } from 'N/types';
+import type { Endpoints, ScriptDeclaration } from '../index.js';
+import { type ControllerOptions } from './endpoint.js';
+/**
+ * Exposes a controller's endpoints as a JSON Suitelet:
+ *
+ *     export const onRequest = defineSuitelet({ name: 'userRoles', scriptId: '...', deployId: '...', browser: false }, userRolesEndpoints);
+ *
+ * A POST's JSON body names the endpoint; any other method is answered 405. The response is the same
+ * envelope a Restlet returns, so a caller does not care which transport answered, except for an
+ * endpoint that returns rawResponse(...): a Suitelet writes that as it is, headers and body or file.
+ * The declaration names the script the controller is deployed as; the generator reads it from this
+ * call. The options carry the authorize hook, run before every handler.
+ */
+export type SuiteletEntryPoint = (context: EntryPoints.Suitelet.onRequestContext) => void;
+export declare function defineSuitelet(script: ScriptDeclaration, endpoints: Endpoints, options?: ControllerOptions): SuiteletEntryPoint;

package/dist/server/defineSuitelet.js

@@ -0,0 +1,20 @@
+import { invokeEndpoint } from './endpoint.js';
+import { writeRawResponse } from './rawResponse.js';
+function writeEnvelope(context, envelope) {
+    context.response.setHeader({ name: 'Content-Type', value: 'application/json' });
+    context.response.write({ output: JSON.stringify(envelope) });
+}
+export function defineSuitelet(script, endpoints, options = {}) {
+    return (context) => {
+        const method = context.request.method.toUpperCase();
+        if (method !== 'POST') {
+            writeEnvelope(context, { status: 405, error: `${script.name} answers POST, not ${method}.`, data: null });
+            return;
+        }
+        const outcome = invokeEndpoint(script.name, endpoints, context.request.body, { ...options, allowRawResponse: true });
+        if (outcome.raw)
+            writeRawResponse(context.response, outcome.raw);
+        else
+            writeEnvelope(context, outcome.envelope);
+    };
+}

package/dist/server/endpoint.d.ts

@@ -0,0 +1,59 @@
+import { type ApiEnvelope, type Endpoints } from '../index.js';
+import { type RawResponseOptions } from './rawResponse.js';
+/**
+ * Endpoints are the transport-agnostic unit of an API controller: named, each a synchronous function
+ * from a request to a response, declared together in the controller file with the request and
+ * response shapes they speak. The handler signatures are the contract: a client is built from
+ * `typeof <name>Endpoints` and calls each endpoint by name. Every call is a POST whose body names the
+ * endpoint. The controller file wraps the map as a Restlet (`defineRestlet`) or a Suitelet
+ * (`defineSuitelet`); switching transport is a change to that one statement and its SDF object, never
+ * to the endpoints.
+ */
+/**
+ * Declares a controller's endpoints. Annotate each handler's parameter with its request type and its
+ * return value with its response type; both reach the clients through the type, and the client
+ * generator reads them from the annotations.
+ */
+export declare function defineEndpoints<TEndpoints extends Endpoints>(endpoints: TEndpoints): TEndpoints;
+/** NetSuite hands a body as either an object or a JSON string. */
+export declare function parseEndpointRequest(rawRequest: unknown): unknown;
+export interface EndpointCall {
+    /** The endpoint named by the request, or undefined when the property is missing. */
+    name: string | undefined;
+    /** Everything else in the body: the endpoint's own input. */
+    request: Record<string, unknown>;
+}
+/** Splits the endpoint name off the parsed body. */
+export declare function readEndpointCall(parsedRequest: unknown): EndpointCall;
+/** The call as the authorize hook sees it, once the endpoint is known to exist. */
+export interface EndpointCallContext {
+    controller: string;
+    endpoint: string;
+    request: Record<string, unknown>;
+}
+/**
+ * Runs before every handler of a controller. Throw an ApiError to reject the call with its status
+ * (`ApiError.forbidden()` for a role the session lacks); return to let it through. The hook decides
+ * from the endpoint name and the request, and from whatever N/runtime says about the caller.
+ */
+export type AuthorizeEndpoint = (call: EndpointCallContext) => void;
+/** What a controller may add to its define call, after the endpoints. */
+export interface ControllerOptions {
+    authorize?: AuthorizeEndpoint;
+}
+export interface InvokeEndpointOptions extends ControllerOptions {
+    /** True for a Suitelet, which can write a raw response; a Restlet cannot, so a raw answer is a 500 there. */
+    allowRawResponse?: boolean;
+}
+/** The envelope to send, or the raw answer to write instead. */
+export interface EndpointOutcome {
+    envelope: ApiEnvelope<unknown>;
+    raw?: RawResponseOptions;
+}
+/**
+ * Runs the endpoint the body names and produces the outcome: 200 with data (or a raw answer), an
+ * ApiError's own status and message (400 without an endpoint name, 404 for an unknown one, whatever
+ * the authorize hook threw), or 500 with the details logged. Audits the outcome and timing either
+ * way. Log titles are constant phrases; the controller, endpoint and ids live in the details object.
+ */
+export declare function invokeEndpoint(controllerName: string, endpoints: Endpoints, rawRequest: unknown, options?: InvokeEndpointOptions): EndpointOutcome;