@factorialco/api-client 3.0.0-beta.2026100139 → 3.0.0

package/dist/esm/errors.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Error types for the Factorial API client.
+ *
+ * Every non-2xx HTTP response is thrown as a {@link FactorialApiError} carrying
+ * the status, method, URL and parsed body. Transport failures (DNS, connection
+ * reset, aborted request) are *not* wrapped — they surface as the underlying
+ * error, typically a `TypeError` from `fetch`.
+ */
+/** Constructor payload for {@link FactorialApiError}. */
+export interface FactorialApiErrorInit {
+    /** HTTP status code, e.g. `401`. */
+    status: number;
+    /** HTTP reason phrase, e.g. `"Unauthorized"`. Empty over HTTP/2. */
+    statusText: string;
+    /** HTTP method of the failed request, e.g. `"GET"`. */
+    method: string;
+    /** Full request URL, including the query string. */
+    url: string;
+    /**
+     * Response body: the parsed JSON when the body was valid JSON, the raw string
+     * for non-JSON bodies, `undefined` when the body was empty.
+     */
+    body: unknown;
+    /** Response headers. Rate-limit and request-id headers live here. */
+    headers?: Headers;
+    /** The raw `Response`, when one was produced. */
+    response?: Response;
+}
+/**
+ * Thrown for every non-2xx response from the Factorial API.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.employees.employees.get({ path: { id: "1" } });
+ * } catch (err) {
+ *   if (err instanceof FactorialApiError) {
+ *     console.error(err.status, err.method, err.url, err.body);
+ *   } else {
+ *     throw err; // transport failure (e.g. a fetch TypeError)
+ *   }
+ * }
+ * ```
+ */
+export declare class FactorialApiError extends Error {
+    /** HTTP status code, e.g. `401`. */
+    readonly status: number;
+    /** HTTP reason phrase, e.g. `"Unauthorized"`. Empty over HTTP/2. */
+    readonly statusText: string;
+    /** HTTP method of the failed request, e.g. `"GET"`. */
+    readonly method: string;
+    /** Full request URL, including the query string. */
+    readonly url: string;
+    /**
+     * Response body: the parsed JSON when the body was valid JSON, the raw string
+     * for non-JSON bodies, `undefined` when the body was empty.
+     */
+    readonly body: unknown;
+    /**
+     * Response headers. Rate-limit and request-id headers live here.
+     *
+     * Non-enumerable, so logging the error stays readable.
+     */
+    readonly headers: Headers;
+    /**
+     * The raw `Response`. Its body stream has already been consumed to populate
+     * {@link FactorialApiError.body} — read that instead.
+     *
+     * Non-enumerable, so logging the error stays readable.
+     */
+    readonly response?: Response;
+    constructor(init: FactorialApiErrorInit);
+}
+/**
+ * `instanceof`-safe check for {@link FactorialApiError}.
+ *
+ * Prefer `err instanceof FactorialApiError`. Use this helper when two copies of
+ * the package may be loaded at once (the ESM + CJS dual-package hazard), where
+ * `instanceof` can fail across realm boundaries.
+ */
+export declare function isFactorialApiError(error: unknown): error is FactorialApiError;
+/**
+ * Converts the raw value thrown by the underlying fetch client for a non-2xx
+ * response (the parsed JSON body, the raw text, or `""`) into a
+ * {@link FactorialApiError}.
+ *
+ * Registered as the client's error interceptor by `FactorialClient`. Values
+ * that do not describe an HTTP error response are returned untouched:
+ *
+ * - no `Response` — a transport failure such as a `fetch` `TypeError`
+ * - an ok `Response` — a failure while parsing a 2xx body
+ * - an `Error` instance — already a usable error, e.g. thrown by a user
+ *   interceptor
+ */
+export declare function toFactorialApiError(error: unknown, response: Response | undefined, request: Request | undefined): unknown;
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAG,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;gBAEjB,IAAI,EAAE,qBAAqB;CAwBxC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAO9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAaT"}

package/dist/esm/errors.js

@@ -0,0 +1,149 @@
+/**
+ * Error types for the Factorial API client.
+ *
+ * Every non-2xx HTTP response is thrown as a {@link FactorialApiError} carrying
+ * the status, method, URL and parsed body. Transport failures (DNS, connection
+ * reset, aborted request) are *not* wrapped — they surface as the underlying
+ * error, typically a `TypeError` from `fetch`.
+ */
+/**
+ * Thrown for every non-2xx response from the Factorial API.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.employees.employees.get({ path: { id: "1" } });
+ * } catch (err) {
+ *   if (err instanceof FactorialApiError) {
+ *     console.error(err.status, err.method, err.url, err.body);
+ *   } else {
+ *     throw err; // transport failure (e.g. a fetch TypeError)
+ *   }
+ * }
+ * ```
+ */
+export class FactorialApiError extends Error {
+    /** HTTP status code, e.g. `401`. */
+    status;
+    /** HTTP reason phrase, e.g. `"Unauthorized"`. Empty over HTTP/2. */
+    statusText;
+    /** HTTP method of the failed request, e.g. `"GET"`. */
+    method;
+    /** Full request URL, including the query string. */
+    url;
+    /**
+     * Response body: the parsed JSON when the body was valid JSON, the raw string
+     * for non-JSON bodies, `undefined` when the body was empty.
+     */
+    body;
+    /**
+     * Response headers. Rate-limit and request-id headers live here.
+     *
+     * Non-enumerable, so logging the error stays readable.
+     */
+    headers;
+    /**
+     * The raw `Response`. Its body stream has already been consumed to populate
+     * {@link FactorialApiError.body} — read that instead.
+     *
+     * Non-enumerable, so logging the error stays readable.
+     */
+    response;
+    constructor(init) {
+        super(formatMessage(init));
+        this.name = "FactorialApiError";
+        this.status = init.status;
+        this.statusText = init.statusText;
+        this.method = init.method;
+        this.url = init.url;
+        this.body = init.body;
+        // `headers` and `response` are hidden from enumeration: console.error(err)
+        // and JSON.stringify(err) would otherwise dump the whole Response object,
+        // burying the fields that identify the failure.
+        Object.defineProperty(this, "headers", {
+            value: init.headers ?? new Headers(),
+            enumerable: false,
+            writable: false,
+            configurable: true,
+        });
+        Object.defineProperty(this, "response", {
+            value: init.response,
+            enumerable: false,
+            writable: false,
+            configurable: true,
+        });
+    }
+}
+/**
+ * `instanceof`-safe check for {@link FactorialApiError}.
+ *
+ * Prefer `err instanceof FactorialApiError`. Use this helper when two copies of
+ * the package may be loaded at once (the ESM + CJS dual-package hazard), where
+ * `instanceof` can fail across realm boundaries.
+ */
+export function isFactorialApiError(error) {
+    return (error instanceof FactorialApiError ||
+        (typeof error === "object" &&
+            error !== null &&
+            error.name === "FactorialApiError"));
+}
+/**
+ * Converts the raw value thrown by the underlying fetch client for a non-2xx
+ * response (the parsed JSON body, the raw text, or `""`) into a
+ * {@link FactorialApiError}.
+ *
+ * Registered as the client's error interceptor by `FactorialClient`. Values
+ * that do not describe an HTTP error response are returned untouched:
+ *
+ * - no `Response` — a transport failure such as a `fetch` `TypeError`
+ * - an ok `Response` — a failure while parsing a 2xx body
+ * - an `Error` instance — already a usable error, e.g. thrown by a user
+ *   interceptor
+ */
+export function toFactorialApiError(error, response, request) {
+    if (response === undefined || response.ok)
+        return error;
+    if (error instanceof Error)
+        return error;
+    return new FactorialApiError({
+        status: response.status,
+        statusText: response.statusText,
+        method: request?.method ?? "UNKNOWN",
+        url: request?.url ?? response.url,
+        // An empty body reaches us as "" because JSON.parse("") throws upstream.
+        body: error === "" ? undefined : error,
+        headers: response.headers,
+        response,
+    });
+}
+/** Longest body excerpt appended to the error message. */
+const EXCERPT_MAX_LENGTH = 200;
+function formatMessage({ status, statusText, method, url, body, }) {
+    const head = `Factorial API ${status}${statusText ? ` ${statusText}` : ""}: ${method} ${url}`;
+    const excerpt = bodyExcerpt(body);
+    return excerpt ? `${head} — ${excerpt}` : head;
+}
+function bodyExcerpt(body) {
+    if (body === undefined || body === null || body === "")
+        return undefined;
+    let text;
+    if (typeof body === "string") {
+        text = body;
+    }
+    else {
+        try {
+            text = JSON.stringify(body) ?? String(body);
+        }
+        catch {
+            // Circular structures and BigInt values make JSON.stringify throw.
+            text = String(body);
+        }
+    }
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    if (!oneLine)
+        return undefined;
+    return oneLine.length > EXCERPT_MAX_LENGTH
+        ? `${oneLine.slice(0, EXCERPT_MAX_LENGTH)}…`
+        : oneLine;
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/esm/generated/sdk.gen.d.ts

@@ -728,7 +728,33 @@ export declare const getApi20261001ResourcesCompensationsPayrollResultsById: <Th
 /**
  * Bulk creates a Payroll result
  *
- * Imports payroll result amounts for employees of a payroll run. Re-posting an (employee, concept) pair replaces its amount; concepts not included in the request are left untouched. Every employee entry must include the company's net_pay concept.
+ * Imports payroll result amounts for employees of an existing payroll run, for example the
+ * figures returned by an external payroll provider. Only Factorial ids are accepted.
+ *
+ * The import is atomic: the whole request is validated before anything is written, and any
+ * error rejects it entirely. A 4xx or 5xx response means nothing was written, so a failed
+ * request can be retried as is.
+ *
+ * The request is rejected when:
+ * - it has no results, an employee entry has no items, it carries more than 1,000 amounts,
+ * or it repeats an employee or a concept for the same employee
+ * - the payroll run, an employee or a payroll concept does not exist in the company
+ * - an employee is not part of the payroll run, that is, is not one of the employees
+ * Factorial lists in that run. On regular runs the employee's contract must cover the run
+ * period, they must not have been terminated more than 60 days before the run starts and,
+ * when the run's cycle is limited to a people group, they must belong to it. Off-cycle
+ * runs only apply the people group and a 365-day termination window. The error lists
+ * these employees in `errors.employee_ids`, so they can be removed and the rest resent.
+ * - a concept is a base salary concept or is disabled
+ * - an employee entry does not include the company's net_pay concept (find its id with
+ * compensations/concepts)
+ * - an amount is outside the signed 32-bit integer range
+ *
+ * Re-posting an (employee, concept) pair replaces its amount and keeps the row id. Pairs not
+ * included in the request are left untouched; there is no delete. Split larger payrolls into
+ * requests of up to 1,000 amounts, keeping all of an employee's items in the same request.
+ * Requires the "Import payroll results" permission.
+ *
  */
 export declare const postApi20261001ResourcesCompensationsPayrollResultsBulkCreate: <ThrowOnError extends boolean = false>(options?: Options<PostApi20261001ResourcesCompensationsPayrollResultsBulkCreateData, ThrowOnError>) => RequestResult<PostApi20261001ResourcesCompensationsPayrollResultsBulkCreateResponses, unknown, ThrowOnError>;
 /**