netsuite-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,457 @@
+interface Logger {
+    debug(message: string, meta?: unknown): void;
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+}
+
+interface OAuthConfig {
+    consumerKey: string;
+    consumerSecret: string;
+    tokenKey: string;
+    tokenSecret: string;
+    realm: string;
+}
+interface NetSuiteConfig {
+    /** OAuth 1.0a (TBA) credentials */
+    auth: OAuthConfig;
+    /** NetSuite account ID (e.g., "1234567" or "1234567_SB1" for sandbox) */
+    accountId: string;
+    /** Request timeout in ms. Default: 30000 */
+    timeout?: number;
+    /** Max retry attempts for transient errors. Default: 3 */
+    maxRetries?: number;
+    /** Initial retry delay in ms. Default: 1000 */
+    retryDelay?: number;
+    /** Default headers added to every request */
+    defaultHeaders?: Record<string, string>;
+    /** Optional logger */
+    logger?: Logger;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface RequestOptions {
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** Override timeout for this request */
+    timeout?: number;
+    /** Override retry count for this request */
+    maxRetries?: number;
+}
+interface NetSuiteResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+    duration: number;
+}
+
+interface RequestContext {
+    url: string;
+    method: HttpMethod;
+    headers: Record<string, string>;
+    body?: unknown;
+    metadata: Record<string, unknown>;
+}
+interface ResponseContext {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+    duration: number;
+}
+type Middleware = (context: RequestContext, next: () => Promise<ResponseContext>) => Promise<ResponseContext>;
+
+declare class HttpTransport {
+    private sign;
+    private axiosInstance;
+    private middlewares;
+    private config;
+    constructor(config: NetSuiteConfig);
+    /** Add a middleware to the chain. Returns `this` for chaining. */
+    use(middleware: Middleware): this;
+    /** Execute an HTTP request with OAuth signing, retry, and middleware. */
+    request<T = unknown>(url: string, options?: RequestOptions): Promise<NetSuiteResponse<T>>;
+    private executeRequest;
+}
+
+/** Raw SuiteQL API response envelope */
+interface SuiteQLRawResponse<T = Record<string, unknown>> {
+    links: Array<{
+        rel: string;
+        href: string;
+    }>;
+    count: number;
+    hasMore: boolean;
+    offset: number;
+    totalResults: number;
+    items: T[];
+}
+/** Options for a SuiteQL query execution */
+interface SuiteQLOptions {
+    /** Maximum rows to fetch per page. Default: 1000, Max: 1000 */
+    pageSize?: number;
+    /** Starting offset. Default: 0 */
+    offset?: number;
+    /** Maximum total rows to fetch across all pages. Default: Infinity */
+    maxRows?: number;
+    /** Override timeout for this query */
+    timeout?: number;
+}
+/** Result of a SuiteQL query with metadata */
+interface SuiteQLResult<T = Record<string, unknown>> {
+    /** All fetched rows */
+    items: T[];
+    /** Total results reported by NetSuite */
+    totalResults: number;
+    /** Number of pages fetched */
+    pagesFetched: number;
+    /** Whether more results exist beyond what was fetched */
+    hasMore: boolean;
+    /** Total execution time in ms */
+    duration: number;
+}
+
+/**
+ * SuiteQL client for executing queries against the NetSuite SuiteQL REST endpoint.
+ *
+ * Handles the `Prefer: transient` header requirement and automatic pagination.
+ */
+declare class SuiteQLClient {
+    private transport;
+    private baseUrl;
+    constructor(transport: HttpTransport, accountId: string);
+    /**
+     * Execute a SuiteQL query and return all matching rows.
+     * Automatically paginates across multiple pages.
+     *
+     * @example
+     * ```ts
+     * const result = await client.suiteql.query<Customer>(
+     *   'SELECT id, companyname, email FROM customer WHERE isinactive = \'F\'',
+     *   { pageSize: 500 }
+     * );
+     * console.log(result.items); // all rows
+     * console.log(result.totalResults); // total count from NetSuite
+     * ```
+     */
+    query<T = Record<string, unknown>>(sql: string, options?: SuiteQLOptions): Promise<SuiteQLResult<T>>;
+    /**
+     * Execute a query and return a single row, or null if not found.
+     *
+     * @example
+     * ```ts
+     * const customer = await client.suiteql.queryOne<Customer>(
+     *   'SELECT id, companyname FROM customer WHERE id = 123'
+     * );
+     * ```
+     */
+    queryOne<T = Record<string, unknown>>(sql: string, options?: Omit<SuiteQLOptions, 'maxRows'>): Promise<T | null>;
+    /**
+     * Execute a query and yield pages as an async generator.
+     * Useful for streaming large result sets without holding everything in memory.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.suiteql.queryPages<Transaction>(
+     *   'SELECT id, tranid, total FROM transaction',
+     *   { pageSize: 500 }
+     * )) {
+     *   await processBatch(page);
+     * }
+     * ```
+     */
+    queryPages<T = Record<string, unknown>>(sql: string, options?: SuiteQLOptions): AsyncGenerator<T[], void, undefined>;
+}
+
+/** Options for listing records */
+interface RecordListOptions {
+    limit?: number;
+    offset?: number;
+    fields?: string[];
+    /** URL query params for filtering */
+    query?: Record<string, string>;
+    expandSubResources?: boolean;
+}
+/** Response from listing records */
+interface RecordListResponse<T = Record<string, unknown>> {
+    links: Array<{
+        rel: string;
+        href: string;
+    }>;
+    count: number;
+    hasMore: boolean;
+    offset: number;
+    totalResults: number;
+    items: T[];
+}
+/** Options for getting a single record */
+interface RecordGetOptions {
+    fields?: string[];
+    expandSubResources?: boolean;
+}
+/**
+ * Common NetSuite record types with autocomplete support.
+ * Any string is accepted for custom/unlisted record types.
+ */
+type RecordType = 'customer' | 'vendor' | 'employee' | 'salesOrder' | 'purchaseOrder' | 'invoice' | 'item' | 'contact' | 'opportunity' | 'journalEntry' | 'creditMemo' | 'inventoryItem' | 'nonInventoryItem' | 'serviceItem' | (string & {});
+
+/**
+ * Client for NetSuite REST Record API v1.
+ * Provides CRUD operations on NetSuite records.
+ */
+declare class RecordClient {
+    private transport;
+    private baseUrl;
+    constructor(transport: HttpTransport, accountId: string);
+    /** Get a record by type and internal ID */
+    get<T = Record<string, unknown>>(recordType: RecordType, id: string | number, options?: RecordGetOptions): Promise<NetSuiteResponse<T>>;
+    /** List records of a given type */
+    list<T = Record<string, unknown>>(recordType: RecordType, options?: RecordListOptions): Promise<NetSuiteResponse<RecordListResponse<T>>>;
+    /** Create a new record */
+    create<T = Record<string, unknown>>(recordType: RecordType, body: Record<string, unknown>): Promise<NetSuiteResponse<T>>;
+    /** Update an existing record (partial update via PATCH) */
+    update<T = Record<string, unknown>>(recordType: RecordType, id: string | number, body: Record<string, unknown>): Promise<NetSuiteResponse<T>>;
+    /** Replace an existing record (full replace via PUT) */
+    replace<T = Record<string, unknown>>(recordType: RecordType, id: string | number, body: Record<string, unknown>): Promise<NetSuiteResponse<T>>;
+    /** Delete a record */
+    delete(recordType: RecordType, id: string | number): Promise<NetSuiteResponse<void>>;
+    /** Upsert: create or update based on external ID */
+    upsert<T = Record<string, unknown>>(recordType: RecordType, externalIdField: string, externalIdValue: string, body: Record<string, unknown>): Promise<NetSuiteResponse<T>>;
+}
+
+interface RestletParams {
+    /** Script ID of the RESTlet */
+    script: string | number;
+    /** Deploy ID of the RESTlet */
+    deploy: string | number;
+    /** Additional query parameters */
+    params?: Record<string, string | number | boolean>;
+}
+/**
+ * Client for calling NetSuite RESTlets.
+ * Auto-builds the RESTlet URL from account ID, script, and deploy IDs.
+ */
+declare class RestletClient {
+    private transport;
+    private baseUrl;
+    constructor(transport: HttpTransport, accountId: string);
+    /** Execute a RESTlet call */
+    call<T = unknown>(restlet: RestletParams, options?: RequestOptions): Promise<NetSuiteResponse<T>>;
+}
+
+/**
+ * Main NetSuite API client.
+ *
+ * Provides namespaced access to SuiteQL, Record, and RESTlet APIs,
+ * plus raw HTTP methods as an escape hatch.
+ *
+ * @example
+ * ```ts
+ * import { NetSuiteClient } from 'netsuite-sdk';
+ *
+ * const client = new NetSuiteClient({
+ *   auth: {
+ *     consumerKey: '...',
+ *     consumerSecret: '...',
+ *     tokenKey: '...',
+ *     tokenSecret: '...',
+ *     realm: '1234567',
+ *   },
+ *   accountId: '1234567',
+ * });
+ *
+ * // SuiteQL
+ * const result = await client.suiteql.query('SELECT id, companyname FROM customer');
+ *
+ * // Records
+ * const customer = await client.records.get('customer', 123);
+ *
+ * // RESTlets
+ * const data = await client.restlets.call({ script: '1', deploy: '1' });
+ * ```
+ */
+declare class NetSuiteClient {
+    /** SuiteQL query execution and builder */
+    readonly suiteql: SuiteQLClient;
+    /** REST Record API CRUD */
+    readonly records: RecordClient;
+    /** RESTlet caller */
+    readonly restlets: RestletClient;
+    private readonly transport;
+    constructor(config: NetSuiteConfig);
+    /** Add middleware to all requests. Returns `this` for chaining. */
+    use(middleware: Middleware): this;
+    /** Make a raw HTTP request (escape hatch for custom endpoints). */
+    request<T = unknown>(url: string, options?: RequestOptions): Promise<NetSuiteResponse<T>>;
+    /** Convenience: GET request */
+    get<T = unknown>(url: string, options?: Omit<RequestOptions, 'method'>): Promise<NetSuiteResponse<T>>;
+    /** Convenience: POST request */
+    post<T = unknown>(url: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<NetSuiteResponse<T>>;
+    /** Convenience: PUT request */
+    put<T = unknown>(url: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<NetSuiteResponse<T>>;
+    /** Convenience: PATCH request */
+    patch<T = unknown>(url: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<NetSuiteResponse<T>>;
+    /** Convenience: DELETE request */
+    delete<T = unknown>(url: string, options?: Omit<RequestOptions, 'method'>): Promise<NetSuiteResponse<T>>;
+}
+
+/**
+ * Fluent builder for constructing SuiteQL queries with basic value escaping.
+ *
+ * @example
+ * ```ts
+ * import { suiteql } from 'netsuite-sdk';
+ *
+ * const sql = suiteql()
+ *   .select('c.id', 'c.companyname', 'c.email')
+ *   .from('customer', 'c')
+ *   .leftJoin('transaction t', 'c.id = t.entity')
+ *   .whereEquals('c.isinactive', 'F')
+ *   .whereNotNull('c.email')
+ *   .groupBy('c.id', 'c.companyname', 'c.email')
+ *   .orderBy('c.companyname', 'ASC')
+ *   .build();
+ * ```
+ */
+declare class SuiteQLBuilder {
+    private _select;
+    private _from;
+    private _joins;
+    private _where;
+    private _groupBy;
+    private _orderBy;
+    private _having;
+    /** Add columns to SELECT clause */
+    select(...columns: string[]): this;
+    /** Set the FROM table, with optional alias */
+    from(table: string, alias?: string): this;
+    /** Add a JOIN clause */
+    join(table: string, condition: string, type?: 'INNER' | 'LEFT' | 'RIGHT'): this;
+    /** Add a LEFT JOIN clause */
+    leftJoin(table: string, condition: string): this;
+    /** Add a RIGHT JOIN clause */
+    rightJoin(table: string, condition: string): this;
+    /** Add a raw WHERE condition */
+    where(condition: string): this;
+    /** Add a WHERE column = value condition. Values are escaped. */
+    whereEquals(column: string, value: string | number | boolean): this;
+    /** Add a WHERE column != value condition. Values are escaped. */
+    whereNotEquals(column: string, value: string | number | boolean): this;
+    /** Add a WHERE column IN (...) condition. Values are escaped. */
+    whereIn(column: string, values: (string | number)[]): this;
+    /** Add a WHERE column IS NULL condition */
+    whereNull(column: string): this;
+    /** Add a WHERE column IS NOT NULL condition */
+    whereNotNull(column: string): this;
+    /** Add a WHERE column BETWEEN start AND end condition. Values are escaped. */
+    whereBetween(column: string, start: string | number, end: string | number): this;
+    /** Add a WHERE column LIKE pattern condition. Value is escaped. */
+    whereLike(column: string, pattern: string): this;
+    /** Add columns to GROUP BY clause */
+    groupBy(...columns: string[]): this;
+    /** Add a HAVING condition (used with GROUP BY) */
+    having(condition: string): this;
+    /** Add a column to ORDER BY clause */
+    orderBy(column: string, direction?: 'ASC' | 'DESC'): this;
+    /** Build the SQL string. Throws if SELECT or FROM is missing. */
+    build(): string;
+    /** Alias for build() */
+    toString(): string;
+}
+/** Factory function for creating a new SuiteQL query builder */
+declare function suiteql(): SuiteQLBuilder;
+
+interface NetSuiteErrorDetail {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    'o:errorCode'?: string;
+    'o:errorDetails'?: Array<{
+        detail?: string;
+        'o:errorCode'?: string;
+        'o:errorPath'?: string;
+    }>;
+}
+declare class NetSuiteError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: NetSuiteErrorDetail;
+    readonly requestUrl?: string;
+    readonly requestMethod?: HttpMethod;
+    constructor(message: string, status: number, code: string, details?: NetSuiteErrorDetail, requestUrl?: string, requestMethod?: HttpMethod);
+    /** Whether this is a retryable error (5xx, timeout, network) */
+    get isRetryable(): boolean;
+    /** Whether this is an auth error (401, 403) */
+    get isAuthError(): boolean;
+    static isNetSuiteError(error: unknown): error is NetSuiteError;
+}
+
+/**
+ * Simple in-memory TTL-based cache for API responses.
+ */
+declare class ResponseCache {
+    private cache;
+    /** Get a cached value, or null if not found or expired. */
+    get<T>(key: string): T | null;
+    /** Set a cached value with a TTL in seconds. */
+    set(key: string, data: unknown, ttlSeconds: number): void;
+    /** Delete a specific cache entry. */
+    delete(key: string): boolean;
+    /** Clear all cached entries. */
+    clear(): void;
+    /** Get the number of entries (including expired). */
+    get size(): number;
+}
+/** Create a cache key from request parameters. */
+declare function createCacheKey(url: string, method: string, params?: unknown): string;
+
+/**
+ * Sliding-window rate limiter.
+ * Tracks requests within a time window and prevents exceeding the limit.
+ */
+declare class RateLimiter {
+    private timestamps;
+    private maxRequests;
+    private windowMs;
+    constructor(maxRequests?: number, windowMs?: number);
+    /** Check if a request can be made without exceeding the limit. */
+    canMakeRequest(): boolean;
+    /** Record that a request was made. */
+    recordRequest(): void;
+    /** Get the number of remaining requests in the current window. */
+    getRemainingRequests(): number;
+    /** Get ms until the next request slot opens. Returns 0 if a slot is available. */
+    getTimeUntilNextSlot(): number;
+    private pruneExpired;
+}
+
+/** Validate a NetSuiteConfig and return an array of error messages (empty = valid). */
+declare function validateConfig(config: unknown): string[];
+
+/**
+ * Format a Date as a NetSuite date string (YYYY-MM-DD).
+ */
+declare function formatNetSuiteDate(date: Date): string;
+/**
+ * Parse a NetSuite date string (YYYY-MM-DD or MM/DD/YYYY) into a Date.
+ */
+declare function parseNetSuiteDate(dateString: string): Date;
+
+/**
+ * Parse a NetSuite error response body into a structured format.
+ */
+declare function parseNetSuiteError(error: unknown): {
+    message: string;
+    code?: string;
+    details?: NetSuiteErrorDetail;
+};
+
+/**
+ * Normalize a NetSuite account ID for use in API URLs.
+ * Sandbox accounts use underscore format (e.g., "1234567_SB1")
+ * but URLs require hyphens (e.g., "1234567-sb1").
+ */
+declare function normalizeAccountId(accountId: string): string;
+
+export { type HttpMethod, type Logger, type Middleware, NetSuiteClient, type NetSuiteConfig, NetSuiteError, type NetSuiteErrorDetail, type NetSuiteResponse, type OAuthConfig, RateLimiter, type RecordGetOptions, type RecordListOptions, type RecordListResponse, type RecordType, type RequestContext, type RequestOptions, ResponseCache, type ResponseContext, type RestletParams, SuiteQLBuilder, type SuiteQLOptions, type SuiteQLRawResponse, type SuiteQLResult, createCacheKey, formatNetSuiteDate, normalizeAccountId, parseNetSuiteDate, parseNetSuiteError, suiteql, validateConfig };