@suiteportal/connector 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,212 @@
+/** Configuration for connecting to a NetSuite account. */
+interface NetSuiteConfig {
+    /** NetSuite account ID (e.g. "1234567" or "1234567_SB1" for sandbox). */
+    accountId: string;
+    /** OAuth 1.0a consumer key (integration record). */
+    consumerKey: string;
+    /** OAuth 1.0a consumer secret. */
+    consumerSecret: string;
+    /** OAuth 1.0a token ID. */
+    tokenId: string;
+    /** OAuth 1.0a token secret. */
+    tokenSecret: string;
+    /** Request timeout in milliseconds. Default: 30000. */
+    timeout?: number;
+    /** Max concurrent requests. Default: 5. */
+    concurrency?: number;
+    /** Max retry attempts for retryable failures. Default: 3. */
+    maxRetries?: number;
+    /** Override the base URL (mainly for testing). */
+    baseUrl?: string;
+}
+/** A single row returned by SuiteQL — column names as keys. */
+type SuiteQLRow = Record<string, unknown>;
+/** Result of a SuiteQL query execution. */
+interface SuiteQLResult<T = SuiteQLRow> {
+    items: T[];
+    totalResults?: number;
+    hasMore: boolean;
+}
+/** Raw response shape from the SuiteQL REST endpoint. */
+interface SuiteQLResponse {
+    items: SuiteQLRow[];
+    totalResults?: number;
+    count?: number;
+    hasMore: boolean;
+    offset: number;
+    links?: Array<{
+        rel: string;
+        href: string;
+    }>;
+}
+/** Parameters needed to build an OAuth 1.0a signature. */
+interface OAuthParams {
+    consumerKey: string;
+    consumerSecret: string;
+    tokenId: string;
+    tokenSecret: string;
+    realm: string;
+    method: string;
+    url: string;
+    timestamp?: string;
+    nonce?: string;
+}
+/** Generic HTTP request options used internally. */
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+}
+/** Generic HTTP response wrapper. */
+interface NetSuiteResponse<T = unknown> {
+    status: number;
+    headers: Headers;
+    data: T;
+}
+
+interface ResolvedConfig extends Required<Omit<NetSuiteConfig, 'baseUrl'>> {
+    baseUrl: string;
+}
+/** Validate config and fill defaults. */
+declare function resolveConfig(config: NetSuiteConfig): ResolvedConfig;
+/**
+ * Derive the NetSuite REST API base URL from the account ID.
+ * Account IDs with underscores (sandbox) have underscores replaced with hyphens.
+ * Example: "1234567_SB1" → "https://1234567-sb1.suitetalk.api.netsuite.com"
+ */
+declare function deriveBaseUrl(accountId: string): string;
+/** Get the realm (account ID in uppercase, underscores preserved). */
+declare function getRealm(accountId: string): string;
+
+/**
+ * Core HTTP client for the NetSuite REST API.
+ * Handles OAuth signing, retries, rate limiting, and timeouts.
+ */
+declare class NetSuiteClient {
+    private readonly config;
+    private readonly rateLimiter;
+    constructor(config: NetSuiteConfig);
+    /** Make an authenticated request to the NetSuite REST API. */
+    request<T = unknown>(options: RequestOptions): Promise<NetSuiteResponse<T>>;
+    /** Get the resolved base URL. */
+    get baseUrl(): string;
+    /** Get the resolved config (read-only). */
+    get resolvedConfig(): Readonly<ResolvedConfig>;
+    private executeRequest;
+    private buildUrl;
+    private handleErrorResponse;
+}
+
+/**
+ * Execute a SuiteQL query and return the first page of results.
+ */
+declare function executeSuiteQL<T = SuiteQLRow>(client: NetSuiteClient, query: string, options?: {
+    limit?: number;
+    offset?: number;
+}): Promise<SuiteQLResult<T>>;
+
+interface PaginationOptions {
+    /** Page size per request. Default: 1000. */
+    pageSize?: number;
+    /** Maximum total rows to fetch. Default: unlimited. */
+    maxRows?: number;
+}
+/**
+ * Execute a SuiteQL query and automatically paginate through all results.
+ * Collects all pages into a single array.
+ */
+declare function executeSuiteQLPaginated<T = SuiteQLRow>(client: NetSuiteClient, query: string, options?: PaginationOptions): Promise<T[]>;
+
+/**
+ * Build the OAuth Authorization header value.
+ * Format: OAuth realm="...", oauth_consumer_key="...", ..., oauth_signature="..."
+ */
+declare function buildAuthorizationHeader(params: OAuthParams): string;
+
+/**
+ * RFC 5849 §3.6 percent-encoding.
+ * Encodes all characters except unreserved (ALPHA, DIGIT, '-', '.', '_', '~').
+ */
+declare function percentEncode(str: string): string;
+/** Generate a random nonce for OAuth requests. */
+declare function generateNonce(): string;
+/** Generate a Unix timestamp string. */
+declare function generateTimestamp(): string;
+/**
+ * Build the OAuth signature base string per RFC 5849 §3.4.1.
+ */
+declare function buildSignatureBaseString(method: string, baseUrl: string, params: Array<[string, string]>): string;
+/**
+ * Sign the base string with HMAC-SHA256.
+ * Signing key = percentEncode(consumerSecret) & percentEncode(tokenSecret)
+ */
+declare function signHmacSha256(baseString: string, consumerSecret: string, tokenSecret: string): string;
+/**
+ * Generate the full OAuth 1.0a signature for a request.
+ * Returns the signature string and the oauth params used (for header construction).
+ */
+declare function generateOAuthSignature(params: OAuthParams): {
+    signature: string;
+    oauthParams: Record<string, string>;
+};
+
+/** Base error class for all NetSuite connector errors. */
+declare class NetSuiteError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined, details?: unknown | undefined);
+}
+/** Authentication or authorization failure. */
+declare class AuthError extends NetSuiteError {
+    constructor(message: string, status?: number, details?: unknown);
+}
+/** Rate limit (429) exceeded. */
+declare class RateLimitError extends NetSuiteError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, details?: unknown);
+}
+/** Request timeout via AbortController. */
+declare class TimeoutError extends NetSuiteError {
+    constructor(timeoutMs: number);
+}
+/** Check if an HTTP status code is retryable. */
+declare function isRetryableStatus(status: number): boolean;
+
+/**
+ * Async semaphore for concurrency governance.
+ * Limits the number of in-flight requests to prevent overwhelming NetSuite.
+ */
+declare class RateLimiter {
+    private readonly maxConcurrent;
+    private active;
+    private queue;
+    constructor(maxConcurrent: number);
+    /** Acquire a slot. Resolves when a slot is available. */
+    acquire(): Promise<void>;
+    /** Release a slot, unblocking the next waiter if any. */
+    release(): void;
+    /** Run an async function within the concurrency limit. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Number of currently active tasks. */
+    get activeCount(): number;
+    /** Number of tasks waiting for a slot. */
+    get waitingCount(): number;
+}
+
+interface RetryOptions {
+    maxRetries: number;
+    /** Base delay in ms before first retry. Default: 500. */
+    baseDelay?: number;
+    /** Maximum delay in ms. Default: 30000. */
+    maxDelay?: number;
+}
+/**
+ * Execute a function with exponential backoff + jitter.
+ * Respects `Retry-After` from RateLimitError.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+
+export { AuthError, NetSuiteClient, type NetSuiteConfig, NetSuiteError, type NetSuiteResponse, type OAuthParams, type PaginationOptions, RateLimitError, RateLimiter, type RequestOptions, type ResolvedConfig, type RetryOptions, type SuiteQLResponse, type SuiteQLResult, type SuiteQLRow, TimeoutError, buildAuthorizationHeader, buildSignatureBaseString, deriveBaseUrl, executeSuiteQL, executeSuiteQLPaginated, generateNonce, generateOAuthSignature, generateTimestamp, getRealm, isRetryableStatus, percentEncode, resolveConfig, signHmacSha256, withRetry };

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+/** Configuration for connecting to a NetSuite account. */
+interface NetSuiteConfig {
+    /** NetSuite account ID (e.g. "1234567" or "1234567_SB1" for sandbox). */
+    accountId: string;
+    /** OAuth 1.0a consumer key (integration record). */
+    consumerKey: string;
+    /** OAuth 1.0a consumer secret. */
+    consumerSecret: string;
+    /** OAuth 1.0a token ID. */
+    tokenId: string;
+    /** OAuth 1.0a token secret. */
+    tokenSecret: string;
+    /** Request timeout in milliseconds. Default: 30000. */
+    timeout?: number;
+    /** Max concurrent requests. Default: 5. */
+    concurrency?: number;
+    /** Max retry attempts for retryable failures. Default: 3. */
+    maxRetries?: number;
+    /** Override the base URL (mainly for testing). */
+    baseUrl?: string;
+}
+/** A single row returned by SuiteQL — column names as keys. */
+type SuiteQLRow = Record<string, unknown>;
+/** Result of a SuiteQL query execution. */
+interface SuiteQLResult<T = SuiteQLRow> {
+    items: T[];
+    totalResults?: number;
+    hasMore: boolean;
+}
+/** Raw response shape from the SuiteQL REST endpoint. */
+interface SuiteQLResponse {
+    items: SuiteQLRow[];
+    totalResults?: number;
+    count?: number;
+    hasMore: boolean;
+    offset: number;
+    links?: Array<{
+        rel: string;
+        href: string;
+    }>;
+}
+/** Parameters needed to build an OAuth 1.0a signature. */
+interface OAuthParams {
+    consumerKey: string;
+    consumerSecret: string;
+    tokenId: string;
+    tokenSecret: string;
+    realm: string;
+    method: string;
+    url: string;
+    timestamp?: string;
+    nonce?: string;
+}
+/** Generic HTTP request options used internally. */
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+}
+/** Generic HTTP response wrapper. */
+interface NetSuiteResponse<T = unknown> {
+    status: number;
+    headers: Headers;
+    data: T;
+}
+
+interface ResolvedConfig extends Required<Omit<NetSuiteConfig, 'baseUrl'>> {
+    baseUrl: string;
+}
+/** Validate config and fill defaults. */
+declare function resolveConfig(config: NetSuiteConfig): ResolvedConfig;
+/**
+ * Derive the NetSuite REST API base URL from the account ID.
+ * Account IDs with underscores (sandbox) have underscores replaced with hyphens.
+ * Example: "1234567_SB1" → "https://1234567-sb1.suitetalk.api.netsuite.com"
+ */
+declare function deriveBaseUrl(accountId: string): string;
+/** Get the realm (account ID in uppercase, underscores preserved). */
+declare function getRealm(accountId: string): string;
+
+/**
+ * Core HTTP client for the NetSuite REST API.
+ * Handles OAuth signing, retries, rate limiting, and timeouts.
+ */
+declare class NetSuiteClient {
+    private readonly config;
+    private readonly rateLimiter;
+    constructor(config: NetSuiteConfig);
+    /** Make an authenticated request to the NetSuite REST API. */
+    request<T = unknown>(options: RequestOptions): Promise<NetSuiteResponse<T>>;
+    /** Get the resolved base URL. */
+    get baseUrl(): string;
+    /** Get the resolved config (read-only). */
+    get resolvedConfig(): Readonly<ResolvedConfig>;
+    private executeRequest;
+    private buildUrl;
+    private handleErrorResponse;
+}
+
+/**
+ * Execute a SuiteQL query and return the first page of results.
+ */
+declare function executeSuiteQL<T = SuiteQLRow>(client: NetSuiteClient, query: string, options?: {
+    limit?: number;
+    offset?: number;
+}): Promise<SuiteQLResult<T>>;
+
+interface PaginationOptions {
+    /** Page size per request. Default: 1000. */
+    pageSize?: number;
+    /** Maximum total rows to fetch. Default: unlimited. */
+    maxRows?: number;
+}
+/**
+ * Execute a SuiteQL query and automatically paginate through all results.
+ * Collects all pages into a single array.
+ */
+declare function executeSuiteQLPaginated<T = SuiteQLRow>(client: NetSuiteClient, query: string, options?: PaginationOptions): Promise<T[]>;
+
+/**
+ * Build the OAuth Authorization header value.
+ * Format: OAuth realm="...", oauth_consumer_key="...", ..., oauth_signature="..."
+ */
+declare function buildAuthorizationHeader(params: OAuthParams): string;
+
+/**
+ * RFC 5849 §3.6 percent-encoding.
+ * Encodes all characters except unreserved (ALPHA, DIGIT, '-', '.', '_', '~').
+ */
+declare function percentEncode(str: string): string;
+/** Generate a random nonce for OAuth requests. */
+declare function generateNonce(): string;
+/** Generate a Unix timestamp string. */
+declare function generateTimestamp(): string;
+/**
+ * Build the OAuth signature base string per RFC 5849 §3.4.1.
+ */
+declare function buildSignatureBaseString(method: string, baseUrl: string, params: Array<[string, string]>): string;
+/**
+ * Sign the base string with HMAC-SHA256.
+ * Signing key = percentEncode(consumerSecret) & percentEncode(tokenSecret)
+ */
+declare function signHmacSha256(baseString: string, consumerSecret: string, tokenSecret: string): string;
+/**
+ * Generate the full OAuth 1.0a signature for a request.
+ * Returns the signature string and the oauth params used (for header construction).
+ */
+declare function generateOAuthSignature(params: OAuthParams): {
+    signature: string;
+    oauthParams: Record<string, string>;
+};
+
+/** Base error class for all NetSuite connector errors. */
+declare class NetSuiteError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined, details?: unknown | undefined);
+}
+/** Authentication or authorization failure. */
+declare class AuthError extends NetSuiteError {
+    constructor(message: string, status?: number, details?: unknown);
+}
+/** Rate limit (429) exceeded. */
+declare class RateLimitError extends NetSuiteError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, details?: unknown);
+}
+/** Request timeout via AbortController. */
+declare class TimeoutError extends NetSuiteError {
+    constructor(timeoutMs: number);
+}
+/** Check if an HTTP status code is retryable. */
+declare function isRetryableStatus(status: number): boolean;
+
+/**
+ * Async semaphore for concurrency governance.
+ * Limits the number of in-flight requests to prevent overwhelming NetSuite.
+ */
+declare class RateLimiter {
+    private readonly maxConcurrent;
+    private active;
+    private queue;
+    constructor(maxConcurrent: number);
+    /** Acquire a slot. Resolves when a slot is available. */
+    acquire(): Promise<void>;
+    /** Release a slot, unblocking the next waiter if any. */
+    release(): void;
+    /** Run an async function within the concurrency limit. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Number of currently active tasks. */
+    get activeCount(): number;
+    /** Number of tasks waiting for a slot. */
+    get waitingCount(): number;
+}
+
+interface RetryOptions {
+    maxRetries: number;
+    /** Base delay in ms before first retry. Default: 500. */
+    baseDelay?: number;
+    /** Maximum delay in ms. Default: 30000. */
+    maxDelay?: number;
+}
+/**
+ * Execute a function with exponential backoff + jitter.
+ * Respects `Retry-After` from RateLimitError.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+
+export { AuthError, NetSuiteClient, type NetSuiteConfig, NetSuiteError, type NetSuiteResponse, type OAuthParams, type PaginationOptions, RateLimitError, RateLimiter, type RequestOptions, type ResolvedConfig, type RetryOptions, type SuiteQLResponse, type SuiteQLResult, type SuiteQLRow, TimeoutError, buildAuthorizationHeader, buildSignatureBaseString, deriveBaseUrl, executeSuiteQL, executeSuiteQLPaginated, generateNonce, generateOAuthSignature, generateTimestamp, getRealm, isRetryableStatus, percentEncode, resolveConfig, signHmacSha256, withRetry };