@factorialco/api-client 1.1.0 → 1.2.0

package/README.md

@@ -57,11 +57,11 @@ Explicit options always take precedence.
 | Variable | Maps to option | Sent as |
 |----------|----------------|---------|
 | `FACTORIAL_API_KEY` | `apiKey` | `x-api-key` header |
-| `FACTORIAL_OAUTH_TOKEN` | `token` | `Authorization: Bearer` |
+| `FACTORIAL_TOKEN` | `token` | `Authorization: Bearer` |
 | `FACTORIAL_BASE_URL` | `baseUrl` | — (defaults to `https://api.factorialhr.com`) |
 
 ```ts
-// No options needed — reads FACTORIAL_API_KEY / FACTORIAL_OAUTH_TOKEN / FACTORIAL_BASE_URL
+// No options needed — reads FACTORIAL_API_KEY / FACTORIAL_TOKEN / FACTORIAL_BASE_URL
 const client = new FactorialClient();
 ```
 
@@ -172,6 +172,56 @@ try {
 You can opt out per client (restoring the `{ data, error }` return shape) with
 `new FactorialClient({ ..., throwOnError: false })`.
 
+## Webhooks
+
+Manage subscriptions through the client, and type your handler payloads with the
+generated webhook catalog (re-exported from the package root).
+
+```ts
+import {
+  FactorialClient,
+  WEBHOOK_CATALOG,
+} from "@factorialco/api-client";
+import type {
+  AtsApplicationCreateWebhook,
+  WebhookSubscriptionType,
+  WebhookPayloadMap,
+} from "@factorialco/api-client";
+
+const client = new FactorialClient({ apiKey: process.env.FACTORIAL_API_KEY });
+
+// Subscribe to an event. The `challenge` is a secret you choose; Factorial echoes
+// it back in the `x-factorial-wh-challenge` header on every delivery so you can
+// verify the request really came from Factorial.
+await client.apiPublic.webhookSubscriptions.create({
+  subscription_type: "ats/application/create",
+  target_url: "https://example.com/webhooks/factorial",
+  company_id: 55,
+  challenge: "a-random-secret-you-generate",
+});
+
+// Type a handler directly…
+function onApplicationCreated(payload: AtsApplicationCreateWebhook) {
+  console.log(payload.id);
+}
+
+// …or dispatch on the runtime subscription_type with full type safety
+function handle<T extends WebhookSubscriptionType>(type: T, payload: WebhookPayloadMap[T]) {
+  /* payload is narrowed to the right type for `type` */
+}
+
+// Discover every event at runtime
+console.log(WEBHOOK_CATALOG.length, "webhook events available");
+```
+
+Factorial delivers the resource object at the **top level** of the POST body (no
+`{ type, data }` envelope). A full event→payload reference and an SDK usage guide
+for coding agents are available as a skill:
+
+```bash
+npx skills add https://github.com/factorialco/factorial-api-sdks --skill factorial-api-sdks
+```
+
 ## Custom base URL
 
 ```ts

package/dist/cjs/index.d.ts

@@ -2,4 +2,5 @@ export { FactorialClient } from "./sdk.js";
 export type { FactorialClientConfig } from "./sdk.js";
 export type { PagedMeta, PaginateOptions } from "./pagination.js";
 export * from "./generated/types.gen.js";
+export * from "./webhooks.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClE,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClE,cAAc,0BAA0B,CAAC;AAGzC,cAAc,eAAe,CAAC"}

package/dist/cjs/index.js

@@ -21,4 +21,7 @@ exports.FactorialClient = void 0;
 var sdk_js_1 = require("./sdk.js");
 Object.defineProperty(exports, "FactorialClient", { enumerable: true, get: function () { return sdk_js_1.FactorialClient; } });
 __exportStar(require("./generated/types.gen.js"), exports);
+// Typed webhook catalog: per-event payload aliases, WebhookSubscriptionType,
+// WebhookPayloadMap, and the runtime WEBHOOK_CATALOG.
+__exportStar(require("./webhooks.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,kDAAkD;AAClD,yCAAyC;AACzC,+DAA+D;AAC/D,mCAA2C;AAAlC,yGAAA,eAAe,OAAA;AAGxB,2DAAyC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,kDAAkD;AAClD,yCAAyC;AACzC,+DAA+D;AAC/D,mCAA2C;AAAlC,yGAAA,eAAe,OAAA;AAGxB,2DAAyC;AACzC,6EAA6E;AAC7E,sDAAsD;AACtD,gDAA8B"}

package/dist/cjs/sdk.d.ts

@@ -20,7 +20,7 @@ export type FactorialClientConfig = Omit<Partial<Config<ClientOptions>>, "baseUr
     /**
      * OAuth2 bearer token — sent as `Authorization: Bearer <token>`.
      * Use this when authenticating via OAuth2 instead of an API key.
-     * Falls back to the `FACTORIAL_OAUTH_TOKEN` env var when omitted.
+     * Falls back to the `FACTORIAL_TOKEN` env var when omitted.
      */
     token?: string;
 };

package/dist/cjs/sdk.js

@@ -5523,10 +5523,10 @@ class FactorialClient {
                 globalThis.process.env
             : {};
         const resolvedApiKey = apiKey ?? env.FACTORIAL_API_KEY;
-        const resolvedToken = token ?? env.FACTORIAL_OAUTH_TOKEN;
+        const resolvedToken = token ?? env.FACTORIAL_TOKEN;
         const resolvedBaseUrl = baseUrl ?? env.FACTORIAL_BASE_URL ?? "https://api.factorialhr.com";
         if (!resolvedApiKey && !resolvedToken) {
-            throw new Error("FactorialClient: provide either apiKey or token (or set FACTORIAL_API_KEY / FACTORIAL_OAUTH_TOKEN)");
+            throw new Error("FactorialClient: provide either apiKey or token (or set FACTORIAL_API_KEY / FACTORIAL_TOKEN)");
         }
         // hey-api calls the auth callback once per security scheme in spec order:
         // 1. { type: 'http', scheme: 'bearer' }  → Authorization: Bearer <token>