@dsptch-work/api-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './gen/index.js';
+export * from './pagination.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+// Package root. Re-exports the generated client from src/gen/ (owned by the generator —
+// see openapi-ts.config.ts) so consumers import from '@dsptch-work/api-client'. This file and
+// its siblings in src/ are hand-authored and survive regeneration, which only touches src/gen/.
+export * from './gen/index.js';
+export * from './pagination.js';

package/dist/pagination.d.ts

@@ -0,0 +1,36 @@
+import type { Meta, Links } from './gen/index.js';
+/** The keyset envelope every list endpoint returns as its success body. */
+interface Page<TItem> {
+    data?: TItem[];
+    meta?: Meta;
+    links?: Links;
+}
+type ListMethod = (options: never) => Promise<{
+    data?: Page<unknown>;
+    error?: unknown;
+}>;
+/** The element type of a list method's page — e.g. `JobResponseObject` for `Jobs.listJobs`. */
+type ItemOf<TList extends ListMethod> = NonNullable<NonNullable<Awaited<ReturnType<TList>>['data']>['data']>[number];
+/**
+ * Walk every page of a cursor-paginated list endpoint, yielding one item at a time.
+ *
+ * Pass a generated list method (e.g. `Jobs.listJobs`) and its options; the item type is inferred
+ * from the method, and the options keep the method's own shape — required where the endpoint needs
+ * a path id, optional otherwise. The generator sends `page[cursor]` from each page's `next_cursor`
+ * and stops when the server reports no more pages (`next_cursor == null`).
+ *
+ * Assumes the client's default `responseStyle` ('fields', i.e. `{ data, error }`). If the endpoint
+ * returns an error, it is thrown.
+ *
+ * @example
+ * for await (const job of paginate(Jobs.listJobs, { query: { 'filter[project_id]': id } })) {
+ *   process(job);
+ * }
+ */
+export declare function paginate<TList extends ListMethod>(list: TList, ...rest: Parameters<TList>): AsyncGenerator<ItemOf<TList>>;
+/**
+ * Drain an async iterable into an array. Convenience for the common case where every page fits in
+ * memory: `const jobs = await collect(paginate(Jobs.listJobs))`.
+ */
+export declare function collect<TItem>(source: AsyncIterable<TItem>): Promise<TItem[]>;
+export {};

package/dist/pagination.js

@@ -0,0 +1,60 @@
+// Hand-written helper (survives regeneration — only src/gen/ is regenerated).
+// Every list endpoint returns the same keyset envelope: { data, meta.page.next_cursor, links.next }.
+// A null next_cursor is the last page. `paginate` turns that shared contract into one async
+// generator, so callers write `for await (const item of paginate(Client.listX))` instead of
+// hand-rolling a `while (next_cursor)` loop per resource.
+/**
+ * Walk every page of a cursor-paginated list endpoint, yielding one item at a time.
+ *
+ * Pass a generated list method (e.g. `Jobs.listJobs`) and its options; the item type is inferred
+ * from the method, and the options keep the method's own shape — required where the endpoint needs
+ * a path id, optional otherwise. The generator sends `page[cursor]` from each page's `next_cursor`
+ * and stops when the server reports no more pages (`next_cursor == null`).
+ *
+ * Assumes the client's default `responseStyle` ('fields', i.e. `{ data, error }`). If the endpoint
+ * returns an error, it is thrown.
+ *
+ * @example
+ * for await (const job of paginate(Jobs.listJobs, { query: { 'filter[project_id]': id } })) {
+ *   process(job);
+ * }
+ */
+export async function* paginate(list, ...rest) {
+    // TList is opaque inside the body (its parameter narrows to `never`), so call it through a plain
+    // fields-style signature. The public signature above is what keeps callers type-safe.
+    const call = list;
+    // Under the constraint `Parameters<TList>` is a one-tuple of `never`, so the rest element reads as
+    // always present; a concrete method whose options are optional really is callable with none.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const base = (rest[0] ?? {});
+    let query = { ...(base.query ?? {}) };
+    for (;;) {
+        const sent = query['page[cursor]'];
+        const { data, error } = await call({ ...base, query });
+        // The endpoint's error is the API's own JSON body, not an Error instance; surfacing it verbatim
+        // is the documented contract so callers can read the server's shape.
+        // eslint-disable-next-line @typescript-eslint/only-throw-error
+        if (error)
+            throw error;
+        for (const item of data?.data ?? [])
+            yield item;
+        const next = data?.meta?.page?.next_cursor;
+        if (next == null)
+            return;
+        // The server should never hand back the cursor we just sent; if it does, following it would
+        // loop forever. There is no page cap otherwise, so guard against it explicitly.
+        if (next === sent)
+            throw new Error(`Pagination cursor did not advance ("${next}"); aborting.`);
+        query = { ...query, 'page[cursor]': next };
+    }
+}
+/**
+ * Drain an async iterable into an array. Convenience for the common case where every page fits in
+ * memory: `const jobs = await collect(paginate(Jobs.listJobs))`.
+ */
+export async function collect(source) {
+    const items = [];
+    for await (const item of source)
+        items.push(item);
+    return items;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@dsptch-work/api-client",
+  "version": "0.1.0",
+  "description": "Generated TypeScript client for the DSPTCH REST API.",
+  "keywords": [
+    "dsptch",
+    "api",
+    "client",
+    "sdk",
+    "openapi",
+    "rest",
+    "typescript"
+  ],
+  "homepage": "https://dsptch.app/support/api/api-v-1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rnwbllabs/dsptch-api.git",
+    "directory": "clients/typescript"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/gen/client.gen.d.ts",
+      "import": "./dist/gen/client.gen.js"
+    },
+    "./zod": {
+      "types": "./dist/gen/zod.gen.d.ts",
+      "import": "./dist/gen/zod.gen.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.97.3",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "generate": "openapi-ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint:package": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}