Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import type { Kysely, KyselyDatabase, KyselyTx } from "@carbon/database/client";
import { getLogger } from "@carbon/logger";
import { sql } from "kysely";
import type {
AuthProvider,
OAuthClientOptions,
ProviderCredentials
} from "./types";
const logger = getLogger("ee", "accounting");
/**
* Execute a database operation with sync triggers disabled.
* This prevents circular trigger loops when syncing from external systems.
*
* Uses PostgreSQL session variable `app.sync_in_progress` which is checked
* by the `dispatch_event_batch` trigger function.
*
* @param db - The Kysely database instance
* @param operation - A callback that receives the transaction and performs DB operations
*/
export async function withTriggersDisabled<T>(
db: Kysely<KyselyDatabase>,
operation: (tx: KyselyTx) => Promise<T>
): Promise<T> {
return db.transaction().execute(async (tx) => {
// Set the session variable to disable event triggers for this transaction
await sql`SET LOCAL "app.sync_in_progress" = 'true'`.execute(tx);
return await operation(tx);
});
}
export type HttpResponse<T> = {
error: boolean;
message: string;
code: number;
data: T | null;
};
export class HTTPClient {
constructor(private baseUrl?: string) {}
async request<T>(
method: string,
path: string,
opts: RequestInit = {}
): Promise<HttpResponse<T>> {
let response!: Response;
try {
response = await this.fetch(method, path, opts);
if (response.status === 429) {
const rateLimitInfo = parseRateLimitInfo(response);
throw new RatelimitError("Rate limit exceeded", rateLimitInfo);
}
return this.parseResponse<T>(response);
} catch (error) {
if (error instanceof RatelimitError) {
throw error;
}
return this.parseResponse<T>(response);
}
}
private fetch(
method: string,
path: string,
opts: RequestInit
): Promise<Response> {
const url = this.baseUrl ? `${this.baseUrl}${path}` : path;
return fetch(url, {
method,
...opts
});
}
private async parseResponse<T>(response: Response): Promise<HttpResponse<T>> {
const contentType = response.headers.get("content-type");
const isJson = contentType?.includes("application/json");
if (!response.ok) {
const text = await response.text();
let parsedData: unknown = text;
// Try to parse JSON error responses for better error details
if (isJson && text) {
try {
parsedData = JSON.parse(text);
} catch {
// Keep as raw string if parsing fails
}
}
return {
error: true,
message: response.statusText,
code: response.status,
data: parsedData as T | null
};
}
if (isJson) {
try {
const text = await response.text();
if (!text || text.trim() === "") {
return {
error: false,
message: response.statusText,
code: response.status,
data: null
};
}
return {
error: false,
message: response.statusText,
code: response.status,
data: JSON.parse(text) as T
};
} catch {
return {
error: true,
message: "Invalid JSON response",
code: response.status,
data: null
};
}
}
return {
error: false,
message: response.statusText,
code: response.status,
data: null
};
}
}
// /********************************************************\
// * Custom Errors Start *
// \********************************************************/
export class NotImplementedError extends Error {
constructor(name: string) {
super(`Method ${name} is not implemented.`);
this.name = "NotImplementedError";
}
}
export interface RateLimitInfo {
/** Seconds to wait before retrying */
retryAfterSeconds: number;
/** Which limit was hit (e.g., "minute", "day") */
limitType?: string;
/** Provider-specific details */
details?: Record<string, unknown>;
}
/**
* The provider's token endpoint rejected the stored grant (invalid_grant /
* invalid_client): the refresh token was revoked, expired, or rotated away by
* another runner and lost. Not transient — retrying cannot mint a new pair;
* only reconnecting the integration can.
*/
export class AccountingAuthError extends Error {
constructor(
public readonly provider: string,
public readonly code: number,
detail: string
) {
super(`[${provider}] authentication failed (HTTP ${code}): ${detail}`);
this.name = "AccountingAuthError";
}
}
export class RatelimitError extends Error {
public rateLimitInfo: RateLimitInfo;
constructor(message: string, rateLimitInfo: RateLimitInfo) {
super(message);
this.name = "RatelimitError";
this.rateLimitInfo = rateLimitInfo;
}
get retryAfterSeconds(): number {
return this.rateLimitInfo.retryAfterSeconds;
}
}
/**
* Parse rate limit info from a 429 response.
* Handles Xero-specific headers but can be extended for other providers.
*/
export function parseRateLimitInfo(response: Response): RateLimitInfo {
// Parse Retry-After header (standard HTTP header, value in seconds)
const retryAfter = response.headers.get("Retry-After");
let retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : 60;
// Fallback to 60 seconds if parsing fails
if (isNaN(retryAfterSeconds) || retryAfterSeconds <= 0) {
retryAfterSeconds = 60;
}
// Parse provider-specific headers
const limitType = response.headers.get("X-Rate-Limit-Problem") ?? undefined;
const details: Record<string, unknown> = {};
// Xero-specific headers
const minuteRemaining = response.headers.get("X-MinLimit-Remaining");
const dayRemaining = response.headers.get("X-DayLimit-Remaining");
const appMinuteRemaining = response.headers.get("X-AppMinLimit-Remaining");
if (minuteRemaining) details.minuteRemaining = parseInt(minuteRemaining, 10);
if (dayRemaining) details.dayRemaining = parseInt(dayRemaining, 10);
if (appMinuteRemaining)
details.appMinuteRemaining = parseInt(appMinuteRemaining, 10);
return {
retryAfterSeconds,
limitType,
details: Object.keys(details).length > 0 ? details : undefined
};
}
/** Structured details from an accounting provider API error */
export interface ApiErrorDetails {
/** HTTP status code (e.g., 400, 401, 500) */
statusCode: number;
/** HTTP status text (e.g., "Bad Request") */
statusText: string;
/** Provider-specific error code if available */
providerErrorCode?: string | number;
/** Provider-specific error type (e.g., "ValidationException") */
providerErrorType?: string;
/** Human-readable error message from the provider */
providerMessage?: string;
/** Validation errors for specific fields/elements */
validationErrors?: Array<{
field?: string;
message: string;
}>;
/** Raw response body for debugging (only logged in development) */
rawResponse?: unknown;
}
/**
* Structured error class for accounting provider API errors.
* Captures detailed error information for debugging and user display.
*/
export class AccountingApiError extends Error {
public readonly details: ApiErrorDetails;
public readonly provider: string;
public readonly operation: string;
constructor(provider: string, operation: string, details: ApiErrorDetails) {
// Build a human-readable message
const messages: string[] = [`${details.statusCode} ${details.statusText}`];
if (details.providerMessage) {
messages.push(details.providerMessage);
}
if (details.validationErrors?.length) {
messages.push(details.validationErrors.map((e) => e.message).join("; "));
}
super(`[${provider}] ${operation} failed: ${messages.join(" - ")}`);
this.name = "AccountingApiError";
this.provider = provider;
this.operation = operation;
this.details = details;
}
/** Get a concise error message suitable for user display */
getUserMessage(): string {
if (this.details.validationErrors?.length) {
return this.details.validationErrors.map((e) => e.message).join("; ");
}
return this.details.providerMessage || this.details.statusText;
}
}
// /********************************************************\
// * Custom Errors End *
// \********************************************************/
// /********************************************************\
// * Xero Error Parsing Start *
// \********************************************************/
/**
* Parses Xero API error responses into structured ApiErrorDetails.
*
* Xero returns errors in several formats:
*
* 1. ValidationException with Elements:
* {
* "ErrorNumber": 10,
* "Type": "ValidationException",
* "Message": "A validation exception occurred",
* "Elements": [{
* "ValidationErrors": [{ "Message": "Code must be unique" }]
* }]
* }
*
* 2. Simple error:
* { "Message": "Something went wrong" }
*
* 3. OAuth error:
* { "error": "invalid_grant", "error_description": "Token expired" }
*
* 4. RFC 7807 problem+json:
* { "type": "...", "title": "...", "detail": "..." }
*/
export function extractXeroErrorDetails(
statusCode: number,
statusText: string,
responseData: unknown
): ApiErrorDetails {
const details: ApiErrorDetails = {
statusCode,
statusText,
rawResponse: responseData
};
// Try to parse if it's a string
let data: unknown = responseData;
if (typeof responseData === "string") {
try {
data = JSON.parse(responseData);
} catch {
// Not JSON, use raw string as message if short enough
if (responseData.length < 500) {
details.providerMessage = responseData;
}
return details;
}
}
if (typeof data !== "object" || data === null) {
return details;
}
const obj = data as Record<string, unknown>;
// Extract error type and code
if (typeof obj.Type === "string") {
details.providerErrorType = obj.Type;
}
if (obj.ErrorNumber !== undefined) {
details.providerErrorCode = obj.ErrorNumber as number;
}
// Extract main message (try multiple common formats)
if (typeof obj.Message === "string") {
details.providerMessage = obj.Message;
} else if (typeof obj.message === "string") {
details.providerMessage = obj.message;
} else if (typeof obj.detail === "string") {
// RFC 7807 format
details.providerMessage = obj.detail;
} else if (typeof obj.error_description === "string") {
// OAuth format
details.providerMessage = obj.error_description;
details.providerErrorType = obj.error as string;
}
// Extract validation errors from Elements array
if (Array.isArray(obj.Elements)) {
const validationErrors: Array<{ field?: string; message: string }> = [];
for (const element of obj.Elements) {
if (element && Array.isArray(element.ValidationErrors)) {
for (const err of element.ValidationErrors) {
if (err && typeof err.Message === "string") {
validationErrors.push({ message: err.Message });
}
}
}
}
if (validationErrors.length > 0) {
details.validationErrors = validationErrors;
}
}
return details;
}
const isDevelopment = process.env.NODE_ENV !== "production";
/**
* Creates and logs an AccountingApiError from an HTTP response, then throws it.
* Logs full error details to console for debugging.
*
* @param operation - Description of the operation that failed (e.g., "create item", "batch upsert contacts")
* @param response - The HTTP response object from HTTPClient
* @throws AccountingApiError
*/
export function throwXeroApiError(
operation: string,
response: { error: boolean; message: string; code: number; data: unknown }
): never {
const details = extractXeroErrorDetails(
response.code,
response.message,
response.data
);
const error = new AccountingApiError("xero", operation, details);
// Log full error details for debugging
const logDetails: Record<string, unknown> = {
statusCode: details.statusCode,
statusText: details.statusText,
providerErrorType: details.providerErrorType,
providerErrorCode: details.providerErrorCode,
providerMessage: details.providerMessage,
validationErrors: details.validationErrors
};
// Only include raw response in development to avoid log bloat
if (isDevelopment) {
logDetails.rawResponse = details.rawResponse;
}
logger.error("Xero API error", { operation, ...logDetails });
throw error;
}
// /********************************************************\
// * Xero Error Parsing End *
// \********************************************************/
export function createOAuthClient({
clientId,
clientSecret,
...options
}: OAuthClientOptions): AuthProvider {
const basicAuth = btoa(`${clientId}:${clientSecret}`);
const http = new HTTPClient();
let creds: Extract<ProviderCredentials, { type: "oauth2" }> = {
type: "oauth2",
accessToken: options.accessToken!,
refreshToken: options.refreshToken!
};
return {
getAuthUrl: options.getAuthUrl,
async exchangeCode(code: string, redirectUri?: string) {
const response = await http.request<{
access_token: string;
refresh_token: string;
expires_in: number;
}>("POST", options.tokenUrl, {
headers: {
"Content-Type": "application/x-www-form-urlencoded",
Authorization: `Basic ${basicAuth}`
},
body: new URLSearchParams({
grant_type: "authorization_code",
code,
redirect_uri: redirectUri ?? options.redirectUri ?? ""
})
});
if (response.error || !response.data?.access_token) {
// Surface the provider's actual rejection (e.g. invalid_grant /
// invalid_client) instead of the useless "[object Object]".
throw new Error(
`Token exchange failed (HTTP ${response.code}): ${
typeof response.data === "string"
? response.data
: JSON.stringify(response.data)
}`
);
}
const newCreds = {
type: "oauth2",
accessToken: response.data.access_token,
refreshToken: response.data.refresh_token,
expiresAt: new Date(
Date.now() + response.data.expires_in * 1000
).toISOString()
} satisfies ProviderCredentials;
creds = {
...creds,
...newCreds
};
options.onTokenRefresh && (await options.onTokenRefresh(newCreds));
return newCreds;
},
async refresh() {
logger.info("Refreshing OAuth tokens", { creds });
if (!creds?.refreshToken) {
throw new Error("No refresh token available");
}
// ponytail: read-then-write CAS; add a pg advisory lock RPC if two
// runners still collide inside the same second.
const stored = options.beforeRefresh && (await options.beforeRefresh());
if (stored && stored.refreshToken !== creds.refreshToken) {
logger.info("Adopting tokens rotated by another runner");
creds = { ...creds, ...stored };
return creds;
}
const response = await http.request<{
access_token: string;
refresh_token: string;
expires_in: number;
}>("POST", options.tokenUrl, {
headers: {
"Content-Type": "application/x-www-form-urlencoded",
Authorization: `Basic ${basicAuth}`
},
body: new URLSearchParams({
grant_type: "refresh_token",
refresh_token: creds.refreshToken
})
});
if (response.error || !response.data?.access_token) {
logger.error("Token refresh failed", {
code: response.code,
message: response.message,
data: response.data
});
const detail =
typeof response.data === "string"
? response.data
: JSON.stringify(response.data);
// 400/401 from the token endpoint is the grant itself being refused
// (invalid_grant / invalid_client) — terminal, see AccountingAuthError.
if (response.code === 400 || response.code === 401) {
throw new AccountingAuthError(
new URL(options.tokenUrl).hostname,
response.code,
detail
);
}
throw new Error(
`Token refresh failed (HTTP ${response.code}): ${detail}`
);
}
const newCreds = {
type: "oauth2",
accessToken: response.data.access_token,
refreshToken: response.data.refresh_token,
expiresAt: new Date(
Date.now() + response.data.expires_in * 1000
).toISOString(),
providerMetadata: creds?.providerMetadata
} satisfies ProviderCredentials;
creds = {
...creds,
...newCreds
};
options.onTokenRefresh && (await options.onTokenRefresh(newCreds));
return newCreds;
},
getCredentials() {
if (!creds) {
throw new Error("No credentials available");
}
return creds;
}
};
}