ashby-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Waits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# ashby-ts
+
+Typed TypeScript client for the [Ashby](https://www.ashbyhq.com) API, generated from [Ashby's published OpenAPI spec](https://developers.ashbyhq.com/openapi/ashby-api.json).
+
+All 173 endpoints across 53 resource namespaces, fully typed. Zero runtime dependencies. Works in Node 18+, Bun, and edge runtimes (it only needs `fetch` and `btoa`).
+
+```bash
+npm install ashby-ts
+# or
+bun add ashby-ts
+```
+
+## Quick start
+
+```ts
+import { Ashby } from "ashby-ts";
+
+const ashby = new Ashby({ apiKey: process.env.ASHBY_API_KEY! });
+
+// every list endpoint is an async iterator; pagination is handled for you
+for await (const job of ashby.job.list({ status: ["Open"] })) {
+  console.log(job.title);
+}
+
+const { results: candidate } = await ashby.candidate.info({ id: "..." });
+```
+
+The client surface mirrors Ashby's own API exactly: their endpoints are RPC-style `noun.verb` calls (`application.list`, `candidate.create`), so the client is `ashby.application.list()`, `ashby.candidate.create()`, and so on for every endpoint in the spec. If you know their API reference, you know this client. Responses come back as Ashby's own envelopes, typed.
+
+## Pagination
+
+Every cursor-paginated endpoint returns a lazy call object. Awaiting it fetches one page. Iterating it fetches everything, following `nextCursor` until the data runs out.
+
+```ts
+// one page
+const page = await ashby.application.list({ limit: 50 });
+page.results; // Application[]
+page.nextCursor; // string | undefined
+
+// or the explicit spelling of the same thing
+const samePage = await ashby.application.list({ limit: 50 }).page();
+
+// every item, across every page
+for await (const app of ashby.application.list({ jobId })) {
+  // breaking early stops fetching; no wasted requests
+}
+
+// collect everything into one array
+const all = await ashby.application.list({ jobId }).all();
+```
+
+## Incremental sync
+
+Ashby's list endpoints support `syncToken` incremental sync, and their docs push it hard for good reason: it's the difference between refetching your whole ATS and fetching what changed. The `sync()` helper drains all pages and hands you the next token.
+
+```ts
+// first sync: everything
+let { results, syncToken } = await ashby.candidate.sync();
+
+// later syncs: only what changed
+({ results, syncToken } = await ashby.candidate.sync({ syncToken }));
+```
+
+`sync()` exists on the 26 namespaces whose list endpoint supports it. The types won't let you call it anywhere else.
+
+## Errors
+
+Ashby reports most failures as HTTP 200 with `{ success: false, errors: [...] }`. The client unwraps that: a successful call resolves with the success envelope, anything else throws `AshbyError` carrying Ashby's actual error details.
+
+```ts
+import { AshbyError } from "ashby-ts";
+
+try {
+  await ashby.application.changeStage({ applicationId, interviewStageId });
+} catch (err) {
+  if (err instanceof AshbyError) {
+    err.status; // HTTP status (200 for logical errors)
+    err.endpoint; // "application.changeStage"
+    err.errors; // [{ message, parameter? }]
+  }
+}
+```
+
+429s and 5xxs are retried twice with backoff, honoring `Retry-After`. Tune with `maxRetries`.
+
+## Escape hatch
+
+If you'd rather call endpoints by path, `request()` is the raw typed transport:
+
+```ts
+const res = await ashby.request("/apiKey.info");
+```
+
+## How it's built
+
+The entire client is generated from Ashby's spec; there is no per-endpoint code to drift out of date.
+
+- `openapi-typescript` turns the vendored spec (`spec/ashby-api.json`) into types
+- the client surface is a mapped type over those generated types: namespaces, methods, request bodies, response envelopes, which endpoints paginate, which support sync
+- the runtime is one small Proxy-based fetch wrapper (~200 lines), because Ashby's API is uniform enough that nothing else is needed
+
+Regenerate against the latest spec with `bun run generate --fetch`. The API reference in [`docs/api.md`](./docs/api.md) is generated from this package's own types with [@openpkg-ts/sdk](https://github.com/ryanwaits/openpkg-ts).
+
+## Notes
+
+- Auth is Ashby's standard scheme: your API key as the Basic auth username, blank password. Keys and permissions are managed in Ashby's admin console.
+- This client talks to your real ATS. Endpoints require the corresponding key permissions (`candidatesRead`, `candidatesWrite`, ...), and write calls do what they say.
+- Not affiliated with Ashby. Ashby's API is versioned by them; this package tracks the published spec and vendored spec updates are explicit, reviewable diffs.
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import type { AshbyClient, RequestOf, RpcPath, SuccessOf } from "./types.js";
+export interface AshbyOptions {
+    /** Ashby API key. Sent as the Basic-auth username with a blank password. */
+    apiKey: string;
+    /** Override the API origin. Defaults to https://api.ashbyhq.com */
+    baseUrl?: string;
+    /** Custom fetch implementation (testing, instrumentation). Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Retries on 429/5xx before giving up. Defaults to 2. Retry-After is honored when present. */
+    maxRetries?: number;
+}
+export interface AshbyErrorDetail {
+    message: string;
+    parameter?: string;
+}
+/** Thrown for HTTP failures and for `success: false` envelopes alike. */
+export declare class AshbyError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    readonly errors: AshbyErrorDetail[];
+    constructor(endpoint: string, status: number, errors: AshbyErrorDetail[]);
+}
+export type Ashby = AshbyClient & {
+    /** Raw escape hatch: call any endpoint by path with full typing. */
+    request<P extends RpcPath>(path: P, body?: RequestOf<P>): Promise<SuccessOf<P>>;
+};
+interface AshbyConstructor {
+    new (options: AshbyOptions): Ashby;
+}
+/**
+ * The Ashby API client.
+ *
+ * ```ts
+ * const ashby = new Ashby({ apiKey: process.env.ASHBY_API_KEY! });
+ * for await (const job of ashby.job.list({ status: ["Open"] })) {
+ *   console.log(job.title);
+ * }
+ * ```
+ */
+export declare const Ashby: AshbyConstructor;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAc,MAAM,YAAY,CAAC;AAEzF,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;gBAExB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE;CAQzE;AAsKD,MAAM,MAAM,KAAK,GAAG,WAAW,GAAG;IAChC,oEAAoE;IACpE,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CACjF,CAAC;AAEF,UAAU,gBAAgB;IACxB,KAAK,OAAO,EAAE,YAAY,GAAG,KAAK,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,EAAE,gBAUY,CAAC"}

package/dist/client.js

@@ -0,0 +1,182 @@
+/** Thrown for HTTP failures and for `success: false` envelopes alike. */
+export class AshbyError extends Error {
+    status;
+    endpoint;
+    errors;
+    constructor(endpoint, status, errors) {
+        const detail = errors.map((e) => e.message).join("; ") || `HTTP ${status}`;
+        super(`${endpoint}: ${detail}`);
+        this.name = "AshbyError";
+        this.status = status;
+        this.endpoint = endpoint;
+        this.errors = errors;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class Core {
+    baseUrl;
+    auth;
+    fetchImpl;
+    maxRetries;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("ashby-ts: apiKey is required");
+        this.baseUrl = (options.baseUrl ?? "https://api.ashbyhq.com").replace(/\/$/, "");
+        this.auth = `Basic ${btoa(`${options.apiKey}:`)}`;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.maxRetries = options.maxRetries ?? 2;
+    }
+    async request(endpoint, body) {
+        for (let attempt = 0;; attempt++) {
+            const res = await this.fetchImpl(`${this.baseUrl}/${endpoint}`, {
+                method: "POST",
+                headers: {
+                    authorization: this.auth,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                body: JSON.stringify(body ?? {}),
+            });
+            if ((res.status === 429 || res.status >= 500) && attempt < this.maxRetries) {
+                const retryAfter = Number(res.headers.get("retry-after"));
+                const delay = retryAfter > 0 ? retryAfter * 1000 : 250 * 2 ** attempt;
+                await sleep(delay);
+                continue;
+            }
+            let json;
+            try {
+                json = (await res.json());
+            }
+            catch {
+                // fall through to the HTTP error below
+            }
+            if (!res.ok)
+                throw new AshbyError(endpoint, res.status, json?.errors ?? []);
+            if (!json || json.success !== true) {
+                throw new AshbyError(endpoint, res.status, json?.errors ?? []);
+            }
+            return json;
+        }
+    }
+    async *paginate(endpoint, body) {
+        let cursor = body?.cursor;
+        for (;;) {
+            const page = await this.request(endpoint, cursor ? { ...body, cursor } : { ...body });
+            const results = Array.isArray(page.results) ? page.results : [];
+            for (const item of results)
+                yield item;
+            if (!page.moreDataAvailable || !page.nextCursor)
+                return;
+            cursor = page.nextCursor;
+        }
+    }
+    async sync(endpoint, body) {
+        const results = [];
+        let cursor;
+        let syncToken;
+        for (;;) {
+            const page = await this.request(endpoint, cursor ? { ...body, cursor } : { ...body });
+            if (Array.isArray(page.results))
+                results.push(...page.results);
+            if (page.syncToken !== undefined)
+                syncToken = page.syncToken;
+            if (!page.moreDataAvailable || !page.nextCursor)
+                break;
+            cursor = page.nextCursor;
+        }
+        return { results, syncToken };
+    }
+}
+/** Lazy thenable for list endpoints: await = one page, for-await = every item. */
+class ListCallImpl {
+    core;
+    endpoint;
+    body;
+    executed;
+    constructor(core, endpoint, body) {
+        this.core = core;
+        this.endpoint = endpoint;
+        this.body = body;
+    }
+    run() {
+        this.executed ??= this.core.request(this.endpoint, this.body ?? {});
+        return this.executed;
+    }
+    then(onfulfilled, onrejected) {
+        return this.run().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.run().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.run().finally(onfinally);
+    }
+    page() {
+        return this.run();
+    }
+    async all() {
+        const items = [];
+        for await (const item of this.core.paginate(this.endpoint, this.body))
+            items.push(item);
+        return items;
+    }
+    [Symbol.asyncIterator]() {
+        return this.core.paginate(this.endpoint, this.body)[Symbol.asyncIterator]();
+    }
+    [Symbol.toStringTag] = "AshbyListCall";
+}
+function buildClient(core) {
+    const namespaces = new Map();
+    return new Proxy(Object.create(null), {
+        get(target, ns) {
+            const own = Reflect.get(target, ns);
+            if (own !== undefined)
+                return own;
+            // "then" must stay undefined so the client itself is never thenable
+            if (typeof ns !== "string" || ns === "then")
+                return undefined;
+            let namespace = namespaces.get(ns);
+            if (!namespace) {
+                const methods = new Map();
+                namespace = new Proxy(Object.create(null), {
+                    get(_t, verb) {
+                        if (typeof verb !== "string" || verb === "then")
+                            return undefined;
+                        let method = methods.get(verb);
+                        if (!method) {
+                            method =
+                                verb === "sync"
+                                    ? (body) => core.sync(`${ns}.list`, body)
+                                    : (body) => new ListCallImpl(core, `${ns}.${verb}`, body);
+                            methods.set(verb, method);
+                        }
+                        return method;
+                    },
+                });
+                namespaces.set(ns, namespace);
+            }
+            return namespace;
+        },
+    });
+}
+/**
+ * The Ashby API client.
+ *
+ * ```ts
+ * const ashby = new Ashby({ apiKey: process.env.ASHBY_API_KEY! });
+ * for await (const job of ashby.job.list({ status: ["Open"] })) {
+ *   console.log(job.title);
+ * }
+ * ```
+ */
+export const Ashby = class {
+    constructor(options) {
+        const core = new Core(options);
+        const client = buildClient(core);
+        Object.defineProperty(client, "request", {
+            value: (path, body) => core.request(path.replace(/^\//, ""), body),
+            enumerable: false,
+        });
+        return client;
+    }
+};