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

package/README.md

@@ -10,15 +10,18 @@ The SDK uses standard semver (`MAJOR.MINOR.PATCH`), independent of the Factorial
 |-------------|----------------------|
 | `1.x.y`     | `2026-04-01`         |
 | `2.x.y`     | `2026-07-01`         |
+| `3.x.y`     | `2026-10-01`         |
 
-Factorial releases new API versions quarterly (Jan/Apr/Jul/Oct).
+Factorial releases new API versions quarterly (Jan/Apr/Jul/Oct). A new major is
+usually cut for a new API version, but can also be cut for a breaking change to
+the SDK itself — which is why `2.x` and `3.x` target the same API version.
 
 See the [Factorial API versioning docs](https://apidoc.factorialhr.com/docs/api-versioning) for details.
 
 ## Installation
 
 ```sh
-npm install @factorialco/api-client@2026-07-01
+npm install @factorialco/api-client@2026-10-01
 ```
 
 ## Quick start
@@ -30,8 +33,10 @@ const client = new FactorialClient({
   apiKey: process.env.FACTORIAL_API_KEY,
 });
 
-const { data: { data: { data, meta } = {}, error } = {}, error } = await client.employees.employees.list();
-console.log(`${meta.total} employees total`);
+const { data: page } = await client.employees.employees.list({
+  query: { only_active: true, only_managers: false },
+});
+console.log(`${page.meta?.total} employees total`);
 ```
 
 ## Authentication
@@ -90,8 +95,8 @@ Every resource exposes the standard methods available in the API:
 
 ```ts
 // List (single page, up to 100 items)
-const { data: { data, meta } = {}, error } = await client.employees.employees.list({
-  query: { only_active: true },
+const { data: page } = await client.employees.employees.list({
+  query: { only_active: true, only_managers: false },
 });
 
 // Get by ID
@@ -115,40 +120,53 @@ await client.timeoff.leaves.delete({ path: { id: 99 } });
 
 // Named actions
 await client.timeoff.leaves.approve({ body: { id: 99 } });
-await client.attendance.shifts.clockIn({ body: { employee_id: 1, , now: new Date().toISOString().slice(0, 19) } });
+await client.attendance.shifts.clockIn({
+  body: { employee_id: 1, now: new Date().toISOString().slice(0, 19) },
+});
 ```
 
 ## Pagination
 
-The Factorial API uses **cursor-based pagination**. All list endpoints return
-`{ data: { data, meta } = {}, error }` where `meta` contains `has_next_page`, `end_cursor`, and `total`.
+The Factorial API uses **cursor-based pagination**. Every list endpoint resolves
+to `{ data: { data, meta }, request, response }`, where `meta` carries
+`has_next_page`, `end_cursor`, and `total`. The spec marks `data` and `meta`
+optional, so access them with `?.`. A non-2xx response throws — see
+[Error handling](#error-handling).
 
 ### Single page
 
 ```ts
-const { data: { data, meta } = {}, error } = await client.employees.employees.list({ query: { limit: 50 } });
-
-// Fetch next page manually
-if (meta.has_next_page) {
-  const page2 = await client.employees.employees.list({
-    query: { limit: 50, after_id: meta.end_cursor },
-  });
-}
+const { data: page } = await client.employees.employees.list({
+  query: { only_active: true, only_managers: false },
+});
+console.log(page.data?.length, page.meta?.has_next_page);
 ```
 
+`limit` and `after_id` work at runtime but are absent from the OpenAPI spec, so
+they are not part of the typed `query`. Prefer `paginate({ limit })` below; to
+cursor by hand, cast the query.
+
 ### Stream all pages (async iterator)
 
 ```ts
-for await (const employee of client.employees.employees.paginate()) {
+for await (const employee of client.employees.employees.paginate({
+  query: { only_active: true, only_managers: false },
+})) {
   console.log(employee.full_name);
 }
 ```
 
+`paginate()` and `all()` accept `limit` (items per request, max 100) and
+`maxItems` (a cap on the total fetched) alongside the endpoint's own options.
+
 ### Collect all into array
 
 ```ts
 // Optional safety cap via maxItems
-const all = await client.employees.employees.all({ maxItems: 500 });
+const all = await client.employees.employees.all({
+  query: { only_active: true, only_managers: false },
+  maxItems: 500,
+});
 ```
 
 Both `paginate()` and `all()` are available on every list endpoint.
@@ -172,23 +190,47 @@ There is no server-side aggregation endpoint; compute totals client-side.
 
 ## Error handling
 
-The client is configured with `throwOnError: true`, so any non-2xx response
-(bad/expired token, wrong base URL, `4xx`/`5xx`) **throws** rather than silently
-resolving to empty data. Wrap calls in `try`/`catch`:
+Any non-2xx response (bad/expired token, wrong base URL, `4xx`/`5xx`) **throws a
+`FactorialApiError`** rather than resolving to empty data. Results carry no
+`error` field — wrap calls in `try`/`catch`:
 
 ```ts
+import { FactorialApiError, FactorialClient } from "@factorialco/api-client";
+
 try {
-  const { data } = await client.employees.employees.list();
+  const { data } = await client.employees.employees.get({ path: { id: "42" } });
   console.log(data);
 } catch (err) {
-  // For HTTP errors, `err` is the API's parsed error body.
-  // For transport failures (DNS/connection), `err` is a TypeError.
-  console.error("Request failed:", err);
+  if (err instanceof FactorialApiError) {
+    console.error(err.status);     // 404
+    console.error(err.method);     // "GET"
+    console.error(err.url);        // full request URL
+    console.error(err.body);       // parsed error body from the API
+    console.error(err.message);    // "Factorial API 404 Not Found: GET https://… — {…}"
+  } else {
+    // Transport failure (DNS, connection reset, abort) — not an HTTP response.
+    throw err;
+  }
 }
 ```
 
-You can opt out per client (restoring the `{ data, error }` return shape) with
-`new FactorialClient({ ..., throwOnError: false })`.
+`FactorialApiError` fields:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `status` | `number` | HTTP status code |
+| `statusText` | `string` | Reason phrase; empty over HTTP/2 |
+| `method` | `string` | Request method |
+| `url` | `string` | Full request URL, including the query string |
+| `body` | `unknown` | Parsed JSON, the raw string for non-JSON, `undefined` when empty |
+| `headers` | `Headers` | Response headers; non-enumerable |
+| `response` | `Response` | Raw response; non-enumerable, body already consumed |
+
+`headers` and `response` are non-enumerable so `console.error(err)` stays
+readable — they are still accessible directly.
+
+Across package copies (the ESM + CJS dual-package hazard) `instanceof` can fail;
+`isFactorialApiError(err)` is a name-based fallback for that case.
 
 ## Webhooks
 

package/dist/cjs/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/cjs/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/cjs/errors.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FactorialApiError = void 0;
+exports.isFactorialApiError = isFactorialApiError;
+exports.toFactorialApiError = toFactorialApiError;
+/**
+ * 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)
+ *   }
+ * }
+ * ```
+ */
+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,
+        });
+    }
+}
+exports.FactorialApiError = FactorialApiError;
+/**
+ * `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.
+ */
+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
+ */
+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/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAoGH,kDAOC;AAeD,kDAiBC;AApHD;;;;;;;;;;;;;;;GAeG;AACH,MAAa,iBAAkB,SAAQ,KAAK;IAC1C,oCAAoC;IAC3B,MAAM,CAAS;IACxB,oEAAoE;IAC3D,UAAU,CAAS;IAC5B,uDAAuD;IAC9C,MAAM,CAAS;IACxB,oDAAoD;IAC3C,GAAG,CAAS;IACrB;;;OAGG;IACM,IAAI,CAAU;IACvB;;;;OAIG;IACM,OAAO,CAAW;IAC3B;;;;;OAKG;IACM,QAAQ,CAAY;IAE7B,YAAY,IAA2B;QACrC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,2EAA2E;QAC3E,0EAA0E;QAC1E,gDAAgD;QAChD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE;YACrC,KAAK,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI,OAAO,EAAE;YACpC,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE;YACtC,KAAK,EAAE,IAAI,CAAC,QAAQ;YACpB,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC;CACF;AApDD,8CAoDC;AAED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,KAAc;IAChD,OAAO,CACL,KAAK,YAAY,iBAAiB;QAClC,CAAC,OAAO,KAAK,KAAK,QAAQ;YACxB,KAAK,KAAK,IAAI;YACb,KAA4B,CAAC,IAAI,KAAK,mBAAmB,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,mBAAmB,CACjC,KAAc,EACd,QAA8B,EAC9B,OAA4B;IAE5B,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,IAAI,iBAAiB,CAAC;QAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,SAAS;QACpC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,QAAQ,CAAC,GAAG;QACjC,yEAAyE;QACzE,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK;QACtC,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,QAAQ;KACT,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,SAAS,aAAa,CAAC,EACrB,MAAM,EACN,UAAU,EACV,MAAM,EACN,GAAG,EACH,IAAI,GACkB;IACtB,MAAM,IAAI,GAAG,iBAAiB,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,IAAI,GAAG,EAAE,CAAC;IAC9F,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,SAAS,WAAW,CAAC,IAAa;IAChC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAEzE,IAAI,IAAY,CAAC;IACjB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;YACnE,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,OAAO,CAAC,MAAM,GAAG,kBAAkB;QACxC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,GAAG;QAC5C,CAAC,CAAC,OAAO,CAAC;AACd,CAAC"}

package/dist/cjs/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>;
 /**