@kombo-api/sdk 0.2.4 → 0.3.3

package/src/types/unrecognized.ts

@@ -16,8 +16,16 @@ export function startCountingUnrecognized() {
   refCount++;
   const start = globalCount;
   return {
-    end: () => {
+    /**
+     * Ends counting and returns the delta.
+     * @param delta - If provided, only this amount is added to the parent counter
+     *   (used for nested unions where we only want to record the winning option's count).
+     *   If not provided, records all counts since start().
+     */
+    end: (delta?: number) => {
       const count = globalCount - start;
+      // Reset globalCount back to start, then add only the specified delta
+      globalCount = start + (delta ?? count);
       if (--refCount === 0) globalCount = 0;
       return count;
     },

package/tests/basic-behavior.spec.ts

@@ -1,7 +1,6 @@
-import { it, expect } from "vitest";
+import { it, expect, describe } from "vitest";
 import { TestContext, describeSdkSuite } from "./helpers/test-context";
 
-// TODO: test basic error handling behavior
 describeSdkSuite("Basic SDK Behavior", () => {
   it("should include API key in Authorization header", async () => {
     const ctx = new TestContext({ apiKey: "my-custom-api-key" });
@@ -159,4 +158,358 @@ describeSdkSuite("Basic SDK Behavior", () => {
     const requestWithoutDeleted = ctx.getLastRequest();
     expect(requestWithoutDeleted.path).toContain("include_deleted=false");
   });
+
+  describe("Pagination Behavior", () => {
+    it("should iterate through multiple pages", async () => {
+      const ctx = new TestContext();
+
+      // Mock 3 pages of results
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag1",
+                  remote_id: null,
+                  name: "Tag 1",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+                {
+                  id: "tag2",
+                  remote_id: null,
+                  name: "Tag 2",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: "cursor_page2",
+            },
+          },
+        },
+      });
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag3",
+                  remote_id: null,
+                  name: "Tag 3",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+                {
+                  id: "tag4",
+                  remote_id: null,
+                  name: "Tag 4",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: "cursor_page3",
+            },
+          },
+        },
+      });
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag5",
+                  remote_id: null,
+                  name: "Tag 5",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: null,
+            },
+          },
+        },
+      });
+
+      const tags = await ctx.kombo.ats.getTags({});
+      const allResults: unknown[] = [];
+
+      for await (const page of tags) {
+        allResults.push(...page.result.data.results);
+      }
+
+      // Verify all 5 tags were collected
+      expect(allResults).toHaveLength(5);
+      expect(allResults.map((r: any) => r.id)).toEqual([
+        "tag1",
+        "tag2",
+        "tag3",
+        "tag4",
+        "tag5",
+      ]);
+
+      // Verify 3 HTTP requests were made
+      const requests = ctx.getRequests();
+      expect(requests).toHaveLength(3);
+    });
+
+    it("should pass cursor parameter to subsequent requests", async () => {
+      const ctx = new TestContext();
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag1",
+                  remote_id: null,
+                  name: "Tag 1",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: "test_cursor_abc123",
+            },
+          },
+        },
+      });
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag2",
+                  remote_id: null,
+                  name: "Tag 2",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: null,
+            },
+          },
+        },
+      });
+
+      const tags = await ctx.kombo.ats.getTags({});
+      for await (const _page of tags) {
+        // Iterate through all pages
+      }
+
+      const requests = ctx.getRequests();
+      expect(requests).toHaveLength(2);
+
+      // First request should NOT include cursor
+      expect(requests[0].path).not.toContain("cursor=");
+
+      // Second request SHOULD include cursor
+      expect(requests[1].path).toContain("cursor=test_cursor_abc123");
+    });
+
+    it("should stop pagination when next is null", async () => {
+      const ctx = new TestContext();
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag1",
+                  remote_id: null,
+                  name: "Tag 1",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+                {
+                  id: "tag2",
+                  remote_id: null,
+                  name: "Tag 2",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: null,
+            },
+          },
+        },
+      });
+
+      const tags = await ctx.kombo.ats.getTags({});
+      const pageCount: number[] = [];
+
+      for await (const _page of tags) {
+        pageCount.push(1);
+      }
+
+      // Verify only 1 page was returned
+      expect(pageCount).toHaveLength(1);
+
+      // Verify only 1 HTTP request was made
+      const requests = ctx.getRequests();
+      expect(requests).toHaveLength(1);
+    });
+
+    it("should preserve query parameters across paginated requests", async () => {
+      const ctx = new TestContext();
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag1",
+                  remote_id: null,
+                  name: "Tag 1",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: "cursor_for_page2",
+            },
+          },
+        },
+      });
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag2",
+                  remote_id: null,
+                  name: "Tag 2",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: null,
+            },
+          },
+        },
+      });
+
+      const tags = await ctx.kombo.ats.getTags({
+        updated_after: new Date("2024-01-01T00:00:00.000Z"),
+      });
+
+      for await (const _page of tags) {
+        // Iterate through all pages
+      }
+
+      const requests = ctx.getRequests();
+      expect(requests).toHaveLength(2);
+
+      // Both requests should include the original query parameters
+      // Check that updated_after parameter is present (URL encoded)
+      expect(requests[0].path).toMatch(/updated_after=2024-01-01T00%3A00%3A00\.000Z/);
+      expect(requests[0].path).not.toContain("cursor=");
+
+      expect(requests[1].path).toMatch(/updated_after=2024-01-01T00%3A00%3A00\.000Z/);
+      expect(requests[1].path).toContain("cursor=cursor_for_page2");
+    });
+
+    it("should support manual pagination with next()", async () => {
+      const ctx = new TestContext();
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag1",
+                  remote_id: null,
+                  name: "Tag 1",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: "manual_cursor_xyz",
+            },
+          },
+        },
+      });
+
+      ctx.mockEndpoint({
+        method: "GET",
+        path: "/v1/ats/tags",
+        response: {
+          body: {
+            status: "success",
+            data: {
+              results: [
+                {
+                  id: "tag2",
+                  remote_id: null,
+                  name: "Tag 2",
+                  changed_at: "2024-01-01T00:00:00.000Z",
+                  remote_deleted_at: null,
+                },
+              ],
+              next: null,
+            },
+          },
+        },
+      });
+
+      const page1 = await ctx.kombo.ats.getTags({});
+      
+      // Verify first page was fetched
+      expect(page1.result.data.results).toBeDefined();
+      expect(page1.result.data.results).toHaveLength(1);
+
+      // Manually call next()
+      const page2Result = await page1.next();
+      
+      // Verify second page was fetched (should not be null if cursor was read correctly)
+      // This will fail if cursor extraction bug exists
+      expect(page2Result).not.toBeNull();
+      if (page2Result) {
+        expect(page2Result.result.data.results).toHaveLength(1);
+        expect(page2Result.result.data.results[0].id).toBe("tag2");
+      }
+
+      // Verify 2 HTTP requests were made
+      const requests = ctx.getRequests();
+      expect(requests).toHaveLength(2);
+      expect(requests[1].path).toContain("cursor=manual_cursor_xyz");
+    });
+  });
 });

package/tests/employee-form-flow.spec.ts

@@ -0,0 +1,175 @@
+import { it, expect } from "vitest";
+import { TestContext, describeSdkSuite } from "./helpers/test-context";
+
+describeSdkSuite("Employee Form Flow", () => {
+  it("should get employee form and return form response", async () => {
+    const ctx = new TestContext();
+
+    ctx.mockEndpoint({
+      method: "GET",
+      path: "/v1/hris/employees/form",
+      response: {
+        body: {
+          status: "success",
+          data: {
+            properties: {
+              firstName: {
+                type: "text",
+                label: "First Name",
+                required: true,
+                description: "Employee's first name",
+                unified_key: "first_name",
+                min_length: 1,
+                max_length: 100,
+              },
+              lastName: {
+                type: "text",
+                label: "Last Name",
+                required: true,
+                description: "Employee's last name",
+                unified_key: "last_name",
+                min_length: 1,
+                max_length: 100,
+              },
+              startDate: {
+                type: "date",
+                label: "Start Date",
+                required: true,
+                description: "Employee's start date",
+                unified_key: "start_date",
+              },
+              keyNumbers: {
+                type: "array",
+                label: "Key Numbers",
+                required: false,
+                description: "Employee's key numbers",
+                unified_key: null,
+                min_items: 2,
+                max_items: 5,
+                item_type: {
+                  type: "number",
+                  label: "Key Number",
+                  required: false,
+                  description: "The number of the keys which belong to the employee",
+                  unified_key: null,
+                  min: 0,
+                  max: 99,
+                },
+              },
+              workLocation: {
+                type: "object",
+                label: "Work Location",
+                required: false,
+                description: "Employee's work location",
+                unified_key: null,
+                properties: {
+                  site: {
+                    type: "single_select",
+                    label: "Site",
+                    required: true,
+                    description: "Employee's site",
+                    unified_key: null,
+                    options: {
+                      type: "inline",
+                      entries: [
+                        {
+                          label: "Site 1",
+                          id: "FXrER44xubBqA9DLgZ3PFNNx",
+                          unified_value: "1",
+                          remote_id: "site_1",
+                        },
+                        {
+                          label: "Site 2",
+                          id: "2rv75UKT2XBoQXsUb9agiTUm",
+                          unified_value: "2",
+                          remote_id: "site_2",
+                        },
+                      ],
+                    },
+                  },
+                },
+              },
+            },
+          },
+          warnings: [],
+        },
+      },
+    });
+
+    // Make the API call
+    const form = await ctx.kombo.hris.getEmployeeForm();
+
+    // Verify the response structure
+    expect(form).toBeDefined();
+    expect(form.status).toBe("success");
+    expect(form.data).toBeDefined();
+    expect(form.data.properties.firstName).toBeDefined();
+    expect(form.data.properties.keyNumbers).toBeDefined();
+    expect(form.warnings).toEqual([]);
+  });
+
+  it("should create employee with form using realistic employee data", async () => {
+    const ctx = new TestContext();
+
+    ctx.mockEndpoint({
+      method: "POST",
+      path: "/v1/hris/employees/form",
+      response: {
+        body: {
+          status: "success",
+          data: {
+            id: "emp-123",
+            remote_id: "remote-emp-123",
+            prehire: {
+              remote_id: null,
+            },
+          },
+          warnings: [],
+        },
+      },
+    });
+
+    // Make the API call with realistic employee properties
+    const result = await ctx.kombo.hris.createEmployeeWithForm({
+      properties: {
+        firstName: "John",
+        lastName: "Doe",
+        startDate: "2025-01-15",
+        keyNumbers: [142, 525, 63],
+        workLocation: {
+          site: "FXrER44xubBqA9DLgZ3PFNNx",
+        },
+      },
+    });
+
+    // Verify the response structure
+    expect(result).toBeDefined();
+    expect(result.status).toBe("success");
+    expect(result.data).toBeDefined();
+    expect(result.data.id).toBe("emp-123");
+    expect(result.data.remote_id).toBe("remote-emp-123");
+    expect(result.warnings).toEqual([]);
+
+    // Verify request body is correctly serialized
+    const request = ctx.getLastRequest();
+    expect(request.method).toBe("POST");
+    expect(request.body).toMatchInlineSnapshot(`
+      {
+        "properties": {
+          "firstName": "John",
+          "keyNumbers": [
+            142,
+            525,
+            63,
+          ],
+          "lastName": "Doe",
+          "startDate": "2025-01-15",
+          "workLocation": {
+            "site": "FXrER44xubBqA9DLgZ3PFNNx",
+          },
+        },
+      }
+    `);
+  });
+});
+

package/tests/helpers/test-context.ts

@@ -1,4 +1,4 @@
-import { describe, beforeAll, afterAll } from "vitest";
+import { describe, beforeAll, afterAll, afterEach } from "vitest";
 import nock from "nock";
 import { Kombo } from "../../src/index";
 
@@ -137,8 +137,11 @@ export function describeSdkSuite(name: string, fn: () => void) {
       nock.disableNetConnect();
     });
 
-    afterAll(() => {
+    afterEach(() => {
       nock.cleanAll();
+    });
+
+    afterAll(() => {
       nock.enableNetConnect();
     });
 

package/tsconfig.json

@@ -1,7 +1,6 @@
 {
   "compilerOptions": {
-    "incremental": true,
-    "tsBuildInfoFile": ".tsbuildinfo",
+    "incremental": false,
     "target": "ES2020",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "jsx": "react-jsx",