@routepact/client 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @routepact/client
+
+ky-based HTTP client for `@routepact/core` pacts. Pass a spec and get back a fully-typed response — params, payload, and return type are all inferred automatically.
+
+## Installation
+
+```bash
+npm install @routepact/client @routepact/core ky zod
+```
+
+## Setup
+
+Create a request function by binding a ky instance and a base URL. You typically do this once and export it for use across your app.
+
+```ts
+import ky from "ky";
+import { createRequest } from "@routepact/client";
+
+const api = ky.create({
+  headers: { "Content-Type": "application/json" },
+  credentials: "include",
+});
+
+export const request = createRequest(api, "https://api.example.com");
+```
+
+## Making requests
+
+Pass a spec to `request`. TypeScript infers everything from the spec — what options are required, what the return type is, and whether `params` or `payload` are needed.
+
+```ts
+import { PostPacts } from "../shared/pacts/post.spec";
+
+// GET /posts — no options needed
+const { resource: posts, meta } = await request(PostPacts.list);
+// posts: { id: string; title: string }[]
+// meta: { total: number; page: number } | undefined
+
+// GET /posts/:id — params are required
+const { resource: post } = await request(PostPacts.getById, {
+  params: { id: "abc" },
+});
+// post: { id: string; title: string; body: string }
+
+// POST /posts — payload is required, typed from the request schema
+const { resource: created } = await request(PostPacts.create, {
+  payload: { title: "Hello", body: "World" },
+});
+// created: { id: string; title: string; body: string }
+
+// PATCH /posts/:id — both params and payload
+const { resource: updated } = await request(PostPacts.update, {
+  params: { id: "abc" },
+  payload: { title: "Updated title" },
+});
+
+// DELETE /posts/:id — params required, no response body
+await request(PostPacts.delete, { params: { id: "abc" } });
+```
+
+## Query parameters
+
+Pass arbitrary query params via the `queries` option. They are appended as a query string.
+
+```ts
+const { resource: posts } = await request(PostPacts.list, {
+  queries: { page: "2", limit: "20", sort: "createdAt" },
+});
+// → GET /posts?page=2&limit=20&sort=createdAt
+```
+
+## Customising the ky instance
+
+Since `createRequest` accepts any `KyInstance`, you can configure ky however you like before passing it in — hooks, auth headers, retry logic, etc.
+
+```ts
+import ky from "ky";
+import { createRequest } from "@routepact/client";
+
+const api = ky.create({
+  prefixUrl: "https://api.example.com",
+  retry: { limit: 2 },
+  hooks: {
+    beforeRequest: [
+      (request) => {
+        request.headers.set("Authorization", `Bearer ${getToken()}`);
+      },
+    ],
+  },
+});
+
+export const request = createRequest(api, "");
+// baseUrl is empty because prefixUrl is set on the ky instance
+```
+
+## Response validation
+
+If the spec defines a `response` or `meta` Zod schema, the client validates the data before returning it. If validation fails, an error is thrown:
+
+```
+Error: resource validation failed
+```
+
+The raw `ZodError` is available as `error.cause`.
+
+If the spec has no response schema, `resource` is typed as `undefined` and no validation runs.
+
+## Multiple API instances
+
+You can create multiple request functions pointing to different APIs:
+
+```ts
+export const internalRequest = createRequest(
+  internalKy,
+  "https://internal.example.com",
+);
+export const externalRequest = createRequest(
+  externalKy,
+  "https://api.partner.com",
+);
+```
+
+## API reference
+
+### `createRequest(kyInstance, baseUrl)`
+
+Returns an async function with the signature:
+
+```ts
+<TPact extends RoutePact>(pact: TPact, options?: RouteOptions<TPact>) =>
+  Promise<RequestResult<TPact>>;
+```
+
+- `pact` — a `RoutePact` from `@routepact/core`
+- `options.params` — required when the path contains `:param` segments
+- `options.payload` — required for `post`, `patch`, `put` when the spec has a request schema
+- `options.queries` — optional `Record<string, string>` appended as a query string
+- Returns `{ resource, meta? }` typed from the spec's response and meta schemas

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./request.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./request.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/request.d.ts

@@ -0,0 +1,14 @@
+import { type RequestResult, type RouteOptions, type RouteOptionsRequired, type RoutePact } from "@routepact/core";
+import type { KyInstance } from "ky";
+/**
+ * Creates a type-safe request function bound to a ky instance and base URL.
+ *
+ * The returned function accepts a route pact and infers the required options
+ * (params, payload, queries) and return type from the pact's Zod schemas.
+ *
+ * @example
+ * const request = createRequest(kyInstance, "https://api.example.com");
+ * const result = await request(UserPacts.getById, { params: { id: "123" } });
+ */
+export declare function createRequest(apiInstance: KyInstance, baseUrl: string): <TPact extends RoutePact>(pact: TPact, ...[options]: RouteOptionsRequired<TPact> extends true ? [options: RouteOptions<TPact>] : [options?: RouteOptions<TPact>]) => Promise<RequestResult<TPact>>;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,IAAI,CAAC;AAGtD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,IACtD,KAAK,SAAS,SAAS,EACnC,MAAM,KAAK,EACX,GAAG,WAAW,oBAAoB,CAAC,KAAK,CAAC,SAAS,IAAI,GAClD,CAAC,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,GAC9B,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,KAClC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CA8DjC"}

package/dist/request.js

@@ -0,0 +1,69 @@
+import { buildEndpoint, exhaustiveGuard, } from "@routepact/core";
+/**
+ * Creates a type-safe request function bound to a ky instance and base URL.
+ *
+ * The returned function accepts a route pact and infers the required options
+ * (params, payload, queries) and return type from the pact's Zod schemas.
+ *
+ * @example
+ * const request = createRequest(kyInstance, "https://api.example.com");
+ * const result = await request(UserPacts.getById, { params: { id: "123" } });
+ */
+export function createRequest(apiInstance, baseUrl) {
+    return async (pact, ...[options]) => {
+        const endpoint = `${baseUrl}${buildEndpoint(pact, options)}`;
+        const responseSchema = pact.validation.response;
+        const responseMetaSchema = pact.validation.meta;
+        let response;
+        switch (pact.method) {
+            case "get":
+                response = apiInstance.get(endpoint);
+                break;
+            case "post":
+                response = apiInstance.post(endpoint, {
+                    json: { resource: options?.payload ?? {} },
+                });
+                break;
+            case "patch":
+                response = apiInstance.patch(endpoint, {
+                    json: { resource: options?.payload ?? {} },
+                });
+                break;
+            case "put":
+                response = apiInstance.put(endpoint, {
+                    json: { resource: options?.payload ?? {} },
+                });
+                break;
+            case "delete":
+                response = apiInstance.delete(endpoint);
+                break;
+            default:
+                exhaustiveGuard(pact.method);
+        }
+        const data = await response.json();
+        if (data.resource && responseSchema) {
+            const dataParseResult = responseSchema.safeParse(data.resource);
+            if (!dataParseResult.success) {
+                throw new Error("resource validation failed", {
+                    cause: dataParseResult.error,
+                });
+            }
+            let meta;
+            if (responseMetaSchema && data.meta) {
+                const metaParseResult = responseMetaSchema.safeParse(data.meta);
+                if (!metaParseResult.success) {
+                    throw new Error("meta validation failed", {
+                        cause: metaParseResult.error,
+                    });
+                }
+                meta = metaParseResult.data;
+            }
+            return {
+                resource: dataParseResult.data,
+                meta,
+            };
+        }
+        return { resource: undefined };
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,eAAe,GAKhB,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,WAAuB,EAAE,OAAe;IACpE,OAAO,KAAK,EACV,IAAW,EACX,GAAG,CAAC,OAAO,CAEwB,EACJ,EAAE;QACjC,MAAM,QAAQ,GAAG,GAAG,OAAO,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;QAE7D,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAChD,MAAM,kBAAkB,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAEhD,IAAI,QAAkC,CAAC;QACvC,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,KAAK,KAAK;gBACR,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACrC,MAAM;YACR,KAAK,MAAM;gBACT,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE;oBACpC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE;iBAC3C,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,OAAO;gBACV,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE;oBACrC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE;iBAC3C,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,KAAK;gBACR,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE;oBACnC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE;iBAC3C,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,QAAQ;gBACX,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACxC,MAAM;YACR;gBACE,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAA0C,CAAC;QAE3E,IAAI,IAAI,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAC;YACpC,MAAM,eAAe,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChE,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,4BAA4B,EAAE;oBAC5C,KAAK,EAAE,eAAe,CAAC,KAAK;iBAC7B,CAAC,CAAC;YACL,CAAC;YAED,IAAI,IAAsD,CAAC;YAC3D,IAAI,kBAAkB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACpC,MAAM,eAAe,GAAG,kBAAkB,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAChE,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CAAC,wBAAwB,EAAE;wBACxC,KAAK,EAAE,eAAe,CAAC,KAAK;qBAC7B,CAAC,CAAC;gBACL,CAAC;gBACD,IAAI,GAAG,eAAe,CAAC,IAA4C,CAAC;YACtE,CAAC;YAED,OAAO;gBACL,QAAQ,EAAE,eAAe,CAAC,IAAI;gBAC9B,IAAI;aACmB,CAAC;QAC5B,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAA0B,CAAC;IACzD,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@routepact/client",
+  "version": "0.1.0",
+  "description": "Ky-based type-safe HTTP client for route pacts — validates responses against Zod schemas",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch"
+  },
+  "dependencies": {
+    "@routepact/core": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "ky": ">=1.0.0",
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "ky": "1.14.3",
+    "zod": "4.1.7"
+  },
+  "keywords": [
+    "routes",
+    "typesafe",
+    "ky",
+    "zod",
+    "client",
+    "fetch"
+  ],
+  "license": "MIT"
+}