@koine/api 1.0.13

package/README.md

@@ -0,0 +1,5 @@
+# @koine/utils
+
+## Code
+
+- Transformative functions like `truncate` or `titleCase` should allow for nullable inputs as much as possible, acceptin both `undefined` and `null`.

package/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Custom `ApiError` class extending `Error` to throw in failed response.
+ *
+ * @see https://eslint.org/docs/rules/no-throw-literal
+ * @see https://github.com/sindresorhus/ky/blob/main/source/errors/HTTPError.ts
+ *
+ */
+export declare class ApiError<DataFailed extends Koine.Api.DataFailed = unknown> extends Error {
+    constructor(result: Koine.Api.ResponseFailed<DataFailed>);
+}
+/**
+ * Create api client
+ *
+ * @param apiName Short name to use in debug logs
+ * @param baseUrl Either relativ eor absolute, it must end without trailing slash
+ */
+export declare const createApi: <TEndpoints extends Koine.Api.Endpoints>(apiName: string, baseUrl: string, options?: Koine.Api.ClientOptions) => Koine.Api.Client<TEndpoints>;

package/core/index.js

@@ -0,0 +1,132 @@
+import { __assign, __awaiter, __extends, __generator } from "tslib";
+import { buildUrlQueryString } from "@koine/utils";
+/**
+ * Custom `ApiError` class extending `Error` to throw in failed response.
+ *
+ * @see https://eslint.org/docs/rules/no-throw-literal
+ * @see https://github.com/sindresorhus/ky/blob/main/source/errors/HTTPError.ts
+ *
+ */
+var ApiError = /** @class */ (function (_super) {
+    __extends(ApiError, _super);
+    function ApiError(result) {
+        var _this = _super.call(this, "Request failed with ".concat(result.status, " ").concat(result.msg)) || this;
+        _this.name = "ApiError";
+        Object.assign(_this, result);
+        return _this;
+    }
+    return ApiError;
+}(Error));
+export { ApiError };
+/**
+ * Create api client
+ *
+ * @param apiName Short name to use in debug logs
+ * @param baseUrl Either relativ eor absolute, it must end without trailing slash
+ */
+export var createApi = function (apiName, baseUrl, options) {
+    var _a = options || {}, adapterBase = _a.adapter, shouldThrowBase = _a.shouldThrow;
+    return ["get", "post", "put", "patch", "delete"].reduce(function (api, method) {
+        api[method] = function (endpoint, options) { return __awaiter(void 0, void 0, void 0, function () {
+            var _a, json, params, _b, headers, _c, timeout, _d, adapter, _e, shouldThrow, requestInit, timeoutNumber, controller, timeoutId, url, response, e_1, result, e_2, pre;
+            return __generator(this, function (_f) {
+                switch (_f.label) {
+                    case 0:
+                        _a = options || {}, json = _a.json, params = _a.params, _b = _a.headers, headers = _b === void 0 ? {} : _b, _c = _a.timeout, timeout = _c === void 0 ? 10000 : _c, _d = _a.adapter, adapter = _d === void 0 ? adapterBase : _d, _e = _a.shouldThrow, shouldThrow = _e === void 0 ? shouldThrowBase : _e;
+                        requestInit = {
+                            method: method.toUpperCase(),
+                            // mode: "cors",
+                            // redirect: "follow",
+                            credentials: "include",
+                            // cache: "no-cache",
+                            referrerPolicy: "no-referrer",
+                            headers: __assign({ "content-type": "application/json" }, headers),
+                        };
+                        timeoutNumber = Number(timeout);
+                        url = "".concat(baseUrl, "/").concat(endpoint + "".replace(/^\/*/, ""));
+                        if (method !== "get" && json) {
+                            requestInit.body = JSON.stringify(json);
+                        }
+                        if (timeoutNumber > 0) {
+                            controller = new AbortController();
+                            timeoutId = setTimeout(function () { return controller.abort(); }, timeoutNumber);
+                            requestInit.signal = controller.signal;
+                        }
+                        if (params) {
+                            // FIXME: ts-expect-error this assertion is not the best, but nevermind for now
+                            // url += buildUrlQueryString(params as unknown as Koine.Api.RequestParams);
+                            url += buildUrlQueryString(params);
+                        }
+                        if (!shouldThrow) return [3 /*break*/, 5];
+                        _f.label = 1;
+                    case 1:
+                        _f.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, fetch(url, requestInit)];
+                    case 2:
+                        response = _f.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        e_1 = _f.sent();
+                        // eslint-disable-next-line no-throw-literal
+                        throw { e: e_1 };
+                    case 4: return [3 /*break*/, 7];
+                    case 5: return [4 /*yield*/, fetch(url, requestInit)];
+                    case 6:
+                        response = _f.sent();
+                        _f.label = 7;
+                    case 7:
+                        if (timeoutId) {
+                            clearTimeout(timeoutId);
+                        }
+                        if (!shouldThrow) return [3 /*break*/, 15];
+                        _f.label = 8;
+                    case 8:
+                        _f.trys.push([8, 13, , 14]);
+                        if (!adapter) return [3 /*break*/, 10];
+                        return [4 /*yield*/, adapter(response, options)];
+                    case 9:
+                        result = _f.sent();
+                        return [3 /*break*/, 12];
+                    case 10: return [4 /*yield*/, response.json()];
+                    case 11:
+                        result = _f.sent();
+                        _f.label = 12;
+                    case 12: return [3 /*break*/, 14];
+                    case 13:
+                        e_2 = _f.sent();
+                        // eslint-disable-next-line no-throw-literal
+                        throw { e: e_2 };
+                    case 14: return [3 /*break*/, 19];
+                    case 15:
+                        if (!adapter) return [3 /*break*/, 17];
+                        return [4 /*yield*/, adapter(response, options)];
+                    case 16:
+                        result = _f.sent();
+                        return [3 /*break*/, 19];
+                    case 17: return [4 /*yield*/, response.json()];
+                    case 18:
+                        result = _f.sent();
+                        _f.label = 19;
+                    case 19:
+                        if (shouldThrow && result.fail) {
+                            // throw new ApiError<Failed>(result);
+                            // I prefer to throw an object literal despite what eslint says
+                            // eslint-disable-next-line no-throw-literal
+                            throw result;
+                        }
+                        if (process.env["NODE_ENV"] !== "production") {
+                            pre = "api[".concat(apiName, "] ").concat(method.toUpperCase(), " to ").concat(url);
+                            if (result.ok) {
+                                console.log("".concat(pre, " success."));
+                            }
+                            else {
+                                console.log("".concat(pre, " failed."));
+                            }
+                        }
+                        return [2 /*return*/, result];
+                }
+            });
+        }); };
+        return api;
+    }, {});
+};

package/core/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": false,
+  "module": "./index.js",
+  "main": "../node/core/index.js",
+  "types": "./index.d.ts"
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./core";
+export * from "./next";
+export * from "./swr";

package/index.js

@@ -0,0 +1,3 @@
+export * from "./core";
+export * from "./next";
+export * from "./swr";

package/next/index.d.ts

@@ -0,0 +1,2 @@
+import type { NextApiResponse } from "next";
+export declare const nextApiResponse: (nextRes: NextApiResponse, response: Koine.Api.ResponseSuccesfull | Koine.Api.ResponseFailed) => void;

package/next/index.js

@@ -0,0 +1,4 @@
+export var nextApiResponse = function (nextRes, response) {
+    // nextRes.status(response.status).json(response.data || response.msg);
+    nextRes.status(response.status).json(response);
+};

package/next/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": false,
+  "module": "./index.js",
+  "main": "../node/next/index.js",
+  "types": "./index.d.ts"
+}

package/node/core/index.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApi = exports.ApiError = void 0;
+var tslib_1 = require("tslib");
+var utils_1 = require("@koine/utils");
+/**
+ * Custom `ApiError` class extending `Error` to throw in failed response.
+ *
+ * @see https://eslint.org/docs/rules/no-throw-literal
+ * @see https://github.com/sindresorhus/ky/blob/main/source/errors/HTTPError.ts
+ *
+ */
+var ApiError = /** @class */ (function (_super) {
+    tslib_1.__extends(ApiError, _super);
+    function ApiError(result) {
+        var _this = _super.call(this, "Request failed with ".concat(result.status, " ").concat(result.msg)) || this;
+        _this.name = "ApiError";
+        Object.assign(_this, result);
+        return _this;
+    }
+    return ApiError;
+}(Error));
+exports.ApiError = ApiError;
+/**
+ * Create api client
+ *
+ * @param apiName Short name to use in debug logs
+ * @param baseUrl Either relativ eor absolute, it must end without trailing slash
+ */
+var createApi = function (apiName, baseUrl, options) {
+    var _a = options || {}, adapterBase = _a.adapter, shouldThrowBase = _a.shouldThrow;
+    return ["get", "post", "put", "patch", "delete"].reduce(function (api, method) {
+        api[method] = function (endpoint, options) { return tslib_1.__awaiter(void 0, void 0, void 0, function () {
+            var _a, json, params, _b, headers, _c, timeout, _d, adapter, _e, shouldThrow, requestInit, timeoutNumber, controller, timeoutId, url, response, e_1, result, e_2, pre;
+            return tslib_1.__generator(this, function (_f) {
+                switch (_f.label) {
+                    case 0:
+                        _a = options || {}, json = _a.json, params = _a.params, _b = _a.headers, headers = _b === void 0 ? {} : _b, _c = _a.timeout, timeout = _c === void 0 ? 10000 : _c, _d = _a.adapter, adapter = _d === void 0 ? adapterBase : _d, _e = _a.shouldThrow, shouldThrow = _e === void 0 ? shouldThrowBase : _e;
+                        requestInit = {
+                            method: method.toUpperCase(),
+                            // mode: "cors",
+                            // redirect: "follow",
+                            credentials: "include",
+                            // cache: "no-cache",
+                            referrerPolicy: "no-referrer",
+                            headers: tslib_1.__assign({ "content-type": "application/json" }, headers),
+                        };
+                        timeoutNumber = Number(timeout);
+                        url = "".concat(baseUrl, "/").concat(endpoint + "".replace(/^\/*/, ""));
+                        if (method !== "get" && json) {
+                            requestInit.body = JSON.stringify(json);
+                        }
+                        if (timeoutNumber > 0) {
+                            controller = new AbortController();
+                            timeoutId = setTimeout(function () { return controller.abort(); }, timeoutNumber);
+                            requestInit.signal = controller.signal;
+                        }
+                        if (params) {
+                            // FIXME: ts-expect-error this assertion is not the best, but nevermind for now
+                            // url += buildUrlQueryString(params as unknown as Koine.Api.RequestParams);
+                            url += (0, utils_1.buildUrlQueryString)(params);
+                        }
+                        if (!shouldThrow) return [3 /*break*/, 5];
+                        _f.label = 1;
+                    case 1:
+                        _f.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, fetch(url, requestInit)];
+                    case 2:
+                        response = _f.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        e_1 = _f.sent();
+                        // eslint-disable-next-line no-throw-literal
+                        throw { e: e_1 };
+                    case 4: return [3 /*break*/, 7];
+                    case 5: return [4 /*yield*/, fetch(url, requestInit)];
+                    case 6:
+                        response = _f.sent();
+                        _f.label = 7;
+                    case 7:
+                        if (timeoutId) {
+                            clearTimeout(timeoutId);
+                        }
+                        if (!shouldThrow) return [3 /*break*/, 15];
+                        _f.label = 8;
+                    case 8:
+                        _f.trys.push([8, 13, , 14]);
+                        if (!adapter) return [3 /*break*/, 10];
+                        return [4 /*yield*/, adapter(response, options)];
+                    case 9:
+                        result = _f.sent();
+                        return [3 /*break*/, 12];
+                    case 10: return [4 /*yield*/, response.json()];
+                    case 11:
+                        result = _f.sent();
+                        _f.label = 12;
+                    case 12: return [3 /*break*/, 14];
+                    case 13:
+                        e_2 = _f.sent();
+                        // eslint-disable-next-line no-throw-literal
+                        throw { e: e_2 };
+                    case 14: return [3 /*break*/, 19];
+                    case 15:
+                        if (!adapter) return [3 /*break*/, 17];
+                        return [4 /*yield*/, adapter(response, options)];
+                    case 16:
+                        result = _f.sent();
+                        return [3 /*break*/, 19];
+                    case 17: return [4 /*yield*/, response.json()];
+                    case 18:
+                        result = _f.sent();
+                        _f.label = 19;
+                    case 19:
+                        if (shouldThrow && result.fail) {
+                            // throw new ApiError<Failed>(result);
+                            // I prefer to throw an object literal despite what eslint says
+                            // eslint-disable-next-line no-throw-literal
+                            throw result;
+                        }
+                        if (process.env["NODE_ENV"] !== "production") {
+                            pre = "api[".concat(apiName, "] ").concat(method.toUpperCase(), " to ").concat(url);
+                            if (result.ok) {
+                                console.log("".concat(pre, " success."));
+                            }
+                            else {
+                                console.log("".concat(pre, " failed."));
+                            }
+                        }
+                        return [2 /*return*/, result];
+                }
+            });
+        }); };
+        return api;
+    }, {});
+};
+exports.createApi = createApi;

package/node/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./core"), exports);
+tslib_1.__exportStar(require("./next"), exports);
+tslib_1.__exportStar(require("./swr"), exports);

package/node/next/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextApiResponse = void 0;
+var nextApiResponse = function (nextRes, response) {
+    // nextRes.status(response.status).json(response.data || response.msg);
+    nextRes.status(response.status).json(response);
+};
+exports.nextApiResponse = nextApiResponse;

package/node/swr/index.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSwrApi = void 0;
+var tslib_1 = require("tslib");
+var swr_1 = require("swr");
+var mutation_1 = require("swr/mutation");
+var core_1 = require("../core");
+function createUseApi(api, method) {
+    return function useApi(endpoint, options, _config) {
+        var _this = this;
+        if (method === "get") {
+            // const fetcher = async (_endpoint: TEndpoint) => {
+            //   try {
+            //     const { ok, data } = await api[method](_endpoint, {
+            //         ...(options || {}),
+            //         shouldThrow: true,
+            //       });
+            //       if (ok) {
+            //         return data;
+            //       }
+            //       throw new Error() as unknown as Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>;
+            //     } catch(e) {
+            //       throw new Error() as unknown as Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>;;
+            //     }
+            //   };
+            // }
+            var fetcher = function () { return tslib_1.__awaiter(_this, void 0, void 0, function () {
+                var data;
+                return tslib_1.__generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0: return [4 /*yield*/, api[method](endpoint, tslib_1.__assign(tslib_1.__assign({}, (options || {})), { shouldThrow: true }))];
+                        case 1:
+                            data = (_a.sent()).data;
+                            return [2 /*return*/, data];
+                    }
+                });
+            }); };
+            var config_1 = _config;
+            // <Data = any, Error = any>(key: Key, config: SWRConfiguration<Data, Error, Fetcher<Data>> | undefined): SWRResponse<Data, Error>;
+            // eslint-disable-next-line react-hooks/rules-of-hooks
+            return (0, swr_1.default)(options ? [endpoint, options] : [endpoint], fetcher, config_1);
+        }
+        var config = _config;
+        var sender = function (_endpoint, _options) { return tslib_1.__awaiter(_this, void 0, void 0, function () {
+            var _a, ok, data;
+            return tslib_1.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0: return [4 /*yield*/, api[method](_endpoint, tslib_1.__assign(tslib_1.__assign({}, (_options.arg || {})), { shouldThrow: true }))];
+                    case 1:
+                        _a = _b.sent(), ok = _a.ok, data = _a.data;
+                        return [2 /*return*/, ok ? data : data];
+                }
+            });
+        }); };
+        // config.fetcher = sender;
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        return (0, mutation_1.default)(
+        // @ts-expect-error FIXME: I can't get it...
+        options ? [endpoint, options] : [endpoint], sender, config);
+    };
+}
+/**
+ * It creates an api client extended with auto-generated SWR wrapper hooks
+ */
+var createSwrApi = function () {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    var api = core_1.createApi.apply(void 0, args);
+    ["get", "post", "put", "patch", "delete"].forEach(function (method) {
+        var hookName = "use".concat(method.charAt(0).toUpperCase() + method.slice(1));
+        api[hookName] = createUseApi(api, method);
+    });
+    return api;
+};
+exports.createSwrApi = createSwrApi;

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@koine/api",
+  "version": "1.0.13",
+  "sideEffects": false,
+  "main": "./node/index.js",
+  "typings": "./index.d.ts",
+  "dependencies": {
+    "next": "^12.1.6",
+    "swr": "^2.0.0-beta.3",
+    "type-fest": "^2.13.0",
+    "tslib": "^2.4.0"
+  },
+  "peerDependencies": {},
+  "module": "./index.js",
+  "types": "./index.d.ts"
+}

package/swr/index.d.ts

@@ -0,0 +1,14 @@
+import { type SWRConfiguration, type SWRResponse } from "swr";
+import { type SWRMutationConfiguration, type SWRMutationResponse } from "swr/mutation";
+declare type KoineApiMethodHookSWR<THookName extends keyof Koine.Api.HooksMapsByName, TEndpoints extends Koine.Api.Endpoints> = <TEndpoint extends Koine.Api.EndpointUrl<TEndpoints>, TMethod extends Koine.Api.RequestMethod = Koine.Api.HooksMapsByName[THookName]>(endpoint: TEndpoint, options?: Koine.Api.EndpointRequestOptions<TEndpoints, TEndpoint, TMethod>, config?: THookName extends "useGet" ? SWRConfiguration<Koine.Api.EndpointResponseSuccesfull<TEndpoints, TEndpoint, TMethod>, Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>> : SWRMutationConfiguration<Koine.Api.EndpointResponseSuccesfull<TEndpoints, TEndpoint, TMethod>, Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>, Koine.Api.EndpointRequestOptions<TEndpoints, TEndpoint, TMethod>, TEndpoint>) => THookName extends "useGet" ? SWRResponse<Koine.Api.EndpointResponseSuccesfull<TEndpoints, TEndpoint, TMethod>, Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>> : SWRMutationResponse<Koine.Api.EndpointResponseSuccesfull<TEndpoints, TEndpoint, TMethod>, Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>, Koine.Api.EndpointRequestOptions<TEndpoints, TEndpoint, TMethod>, TEndpoint>;
+/**
+ * It creates an api client extended with auto-generated SWR wrapper hooks
+ */
+export declare const createSwrApi: <TEndpoints extends Koine.Api.Endpoints>(apiName: string, baseUrl: string, options?: Koine.Api.ClientOptions | undefined) => Koine.Api.Client<TEndpoints> & {
+    useGet: KoineApiMethodHookSWR<"useGet", TEndpoints>;
+    usePost: KoineApiMethodHookSWR<"usePost", TEndpoints>;
+    usePut: KoineApiMethodHookSWR<"usePut", TEndpoints>;
+    usePatch: KoineApiMethodHookSWR<"usePatch", TEndpoints>;
+    useDelete: KoineApiMethodHookSWR<"useDelete", TEndpoints>;
+};
+export {};

package/swr/index.js

@@ -0,0 +1,73 @@
+import { __assign, __awaiter, __generator } from "tslib";
+import useSWR from "swr";
+import useSWRMutation from "swr/mutation";
+import { createApi } from "../core";
+function createUseApi(api, method) {
+    return function useApi(endpoint, options, _config) {
+        var _this = this;
+        if (method === "get") {
+            // const fetcher = async (_endpoint: TEndpoint) => {
+            //   try {
+            //     const { ok, data } = await api[method](_endpoint, {
+            //         ...(options || {}),
+            //         shouldThrow: true,
+            //       });
+            //       if (ok) {
+            //         return data;
+            //       }
+            //       throw new Error() as unknown as Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>;
+            //     } catch(e) {
+            //       throw new Error() as unknown as Koine.Api.EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>;;
+            //     }
+            //   };
+            // }
+            var fetcher = function () { return __awaiter(_this, void 0, void 0, function () {
+                var data;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0: return [4 /*yield*/, api[method](endpoint, __assign(__assign({}, (options || {})), { shouldThrow: true }))];
+                        case 1:
+                            data = (_a.sent()).data;
+                            return [2 /*return*/, data];
+                    }
+                });
+            }); };
+            var config_1 = _config;
+            // <Data = any, Error = any>(key: Key, config: SWRConfiguration<Data, Error, Fetcher<Data>> | undefined): SWRResponse<Data, Error>;
+            // eslint-disable-next-line react-hooks/rules-of-hooks
+            return useSWR(options ? [endpoint, options] : [endpoint], fetcher, config_1);
+        }
+        var config = _config;
+        var sender = function (_endpoint, _options) { return __awaiter(_this, void 0, void 0, function () {
+            var _a, ok, data;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0: return [4 /*yield*/, api[method](_endpoint, __assign(__assign({}, (_options.arg || {})), { shouldThrow: true }))];
+                    case 1:
+                        _a = _b.sent(), ok = _a.ok, data = _a.data;
+                        return [2 /*return*/, ok ? data : data];
+                }
+            });
+        }); };
+        // config.fetcher = sender;
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        return useSWRMutation(
+        // @ts-expect-error FIXME: I can't get it...
+        options ? [endpoint, options] : [endpoint], sender, config);
+    };
+}
+/**
+ * It creates an api client extended with auto-generated SWR wrapper hooks
+ */
+export var createSwrApi = function () {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    var api = createApi.apply(void 0, args);
+    ["get", "post", "put", "patch", "delete"].forEach(function (method) {
+        var hookName = "use".concat(method.charAt(0).toUpperCase() + method.slice(1));
+        api[hookName] = createUseApi(api, method);
+    });
+    return api;
+};

package/swr/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": false,
+  "module": "./index.js",
+  "main": "../node/swr/index.js",
+  "types": "./index.d.ts"
+}

package/typings.d.ts

@@ -0,0 +1,306 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+type _Response = Response;
+
+declare namespace Koine.Api {
+  // @see https://stackoverflow.com/a/60702896/1938970
+  import { Exact } from "type-fest";
+
+  //////////////////////////////////////////////////////////////////////////////
+  //
+  // Client
+  //
+  //////////////////////////////////////////////////////////////////////////////
+
+  type ClientCreator<TEndpoints extends Endpoints> = (
+    apiName: string,
+    baseUrl: string,
+    options?: ClientOptions
+  ) => Client<TEndpoints>;
+
+  type ClientOptions = {
+    adapter?: ResponseAdapter;
+    shouldThrow?: boolean;
+  };
+
+  type ClientMethod<
+    TMethod extends RequestMethod,
+    TEndpoints extends Endpoints
+  > = <
+    TEndpoint extends EndpointUrl<TEndpoints>,
+    TOptions extends EndpointRequestOptions<TEndpoints, TEndpoint, TMethod>,
+    TSuccesfull extends Koine.Api.DataSuccesfull = Koine.Api.EndpointResponseSuccesfull<
+      TEndpoints,
+      TEndpoint,
+      TMethod
+    >,
+    TFailed extends Koine.Api.DataFailed = Koine.Api.EndpointResponseFailed<
+      TEndpoints,
+      TEndpoint,
+      TMethod
+    >
+  >(
+    endpoint: TEndpoint,
+    options?: TOptions
+    // ) => Promise<EndpointResponse<TEndpoints, TEndpoint, TMethod>>;
+  ) => Promise<Response<TSuccesfull, TFailed>>;
+
+  /**
+   * The `api` interface generated by `createApi`
+   */
+  type Client<TEndpoints> = {
+    [TMethod in RequestMethod]: ClientMethod<TMethod, TEndpoints>;
+  };
+
+  //////////////////////////////////////////////////////////////////////////////
+  //
+  // Endpoints
+  //
+  //////////////////////////////////////////////////////////////////////////////
+
+  type EndpointRequestOptions<
+    TEndpoints extends Endpoints,
+    TEndpoint extends EndpointUrl<TEndpoints>,
+    TMethod extends RequestMethod
+  > = RequestOptions<
+    TMethod,
+    TEndpoints[TEndpoint][Uppercase<TMethod>]["request"],
+    TEndpoints[TEndpoint][Uppercase<TMethod>]["params"]
+  >;
+
+  type EndpointResponseSuccesfull<
+    TEndpoints extends Endpoints,
+    TEndpoint extends EndpointUrl<TEndpoints>,
+    TMethod extends RequestMethod
+  > = TEndpoints[TEndpoint][Uppercase<TMethod>]["response"];
+
+  type EndpointResponseFailed<
+    TEndpoints extends Endpoints,
+    TEndpoint extends EndpointUrl<TEndpoints>,
+    TMethod extends RequestMethod
+  > = TEndpoints[TEndpoint][Uppercase<TMethod>]["error"];
+
+  type EndpointResponse<
+    TEndpoints extends Endpoints,
+    TEndpoint extends EndpointUrl<TEndpoints>,
+    TMethod extends RequestMethod
+  > = Response<
+    EndpointResponseSuccesfull<TEndpoints, TEndpoint, TMethod>,
+    EndpointResponseFailed<TEndpoints, TEndpoint, TMethod>
+  >;
+
+  //////////////////////////////////////////////////////////////////////////////
+  //
+  // Defintions
+  //
+  //////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Validate the `Endpoints` definition against the `Endpoint` shape defined
+   * here.
+   *
+   * FIXME: this does not work yet...constraining the API endpoints definitions
+   *
+   * @see https://github.com/sindresorhus/type-fest/blob/main/source/exact.d.ts
+   * @see https://fettblog.eu/typescript-match-the-exact-object-shape/
+   * @see https://stackoverflow.com/a/51496652/1938970
+   * @see https://github.com/Microsoft/TypeScript/issues/12936
+   */
+  // type DefineEndpoint<T> =
+  //   T extends Endpoint ?
+  //   Exclude<keyof T, keyof Endpoint> extends never ?
+  //   T : "Endpoint must follow `Koine.Api.Endpoint` shape" : never;
+  type DefineEndpoint<T extends EndpointShape> = T;
+  type DefineEndpoints<T extends Endpoints> = {};
+  type EndpointShape = { [TMethod in Uppercase<RequestMethod>]?: DataTypes };
+
+  type Endpoints = readonly Record<string, Endpoint>;
+  type Endpoint = {
+    [TMethod in Uppercase<RequestMethod>]?: DataTypes<TMethod>;
+  };
+
+  type EndpointUrl<TEndpoints extends Endpoints> = Extract<keyof TEndpoints, string>;
+
+  type DataTypes<TMethod extends Uppercase<RequestMethod>> =
+    TMethod extends "GET"
+      ? {
+          /**
+           * The JSON response data returned by the request in case of success
+           */
+          response?: null | unknown;
+          /**
+           * The parameters to encode in the URL of the request
+           */
+          params?: RequestParams;
+          /**
+           * The shape of the error data returned by the request in case of
+           * failure
+           */
+          error?: null | unknown;
+        }
+      : {
+          /**
+           * The request body of a non-GET request
+           */
+          request?: null | unknown;
+          /**
+           * The JSON response data returned by the request in case of success
+           */
+          response?: null | unknown;
+          /**
+           * The parameters to encode in the URL of the request
+           */
+          params?: RequestParams;
+          /**
+           * The shape of the error data returned by the request in case of
+           * failure
+           */
+          error?: null | unknown;
+        };
+
+  //////////////////////////////////////////////////////////////////////////////
+  //
+  // Request
+  //
+  //////////////////////////////////////////////////////////////////////////////
+
+  type RequestParams = undefined | null | Record<string | number, unknown>;
+
+  /**
+   * Shared request options (for every request method)
+   *
+   * Client options can be overriden here at request level.
+   */
+  type RequestOptionsShared = ClientOptions & {
+    /**
+     * Headers will be merged with
+     * ```
+     * { "content-type": "application/json" }
+     * ```
+     */
+    headers?: RequestInit["headers"];
+    /**
+     * Timeout in `ms`, if `falsy` there is no timeout
+     *
+     * @default 10000
+     */
+    timeout?: number | false | null;
+  };
+
+  /**
+   * Request options
+   *
+   * Client options can be overriden here at request level.
+   */
+  type RequestOptions<
+    TMethod extends RequestMethod,
+    TJson extends Record<string, unknown> = {},
+    TParams extends RequestParams = {}
+  > = RequestOptionsShared &
+    ([TMethod] extends ["get"]
+      ? {
+          /**
+           * JSON request body
+           */
+          json?: TJson;
+          /**
+           * Params will be serialized into a string and appended to the URL
+           */
+          params?: TParams;
+        }
+      : {
+          /**
+           * JSON request body
+           *
+           * @default {}
+           */
+          json?: TJson;
+          /**
+           * Params will be serialized into a string and appended to the URL
+           */
+          params?: TParams;
+        });
+
+  type RequestMethod = "get" | "post" | "put" | "patch" | "delete";
+
+  //////////////////////////////////////////////////////////////////////////////
+  //
+  // Response
+  //
+  //////////////////////////////////////////////////////////////////////////////
+
+  type DataSuccesfull = unknown;
+
+  type DataFailed = unknown;
+
+  type ResponseShared<
+    T extends Record<string, unknown> = Record<string, unknown>
+  > = T & {
+    status: _Response["status"];
+    msg: _Response["statusText"];
+  };
+
+  type ResponseSuccesfull<Data extends DataSuccesfull = DataSuccesfull> = {
+    status: _Response["status"];
+    msg: _Response["statusText"];
+    ok: true;
+    fail?: false;
+    data: Data;
+  };
+
+  type ResponseFailed<Data extends DataFailed = DataFailed> = {
+    status: _Response["status"];
+    msg: _Response["statusText"];
+    ok?: false;
+    fail: true;
+    data: Data;
+  };
+
+  type Response<Succesfull extends DataSuccesfull, Failed extends DataFailed> =
+    // FIXME: without the type duplication below the following two lines do not
+    // work as they do not narrow the type when checking for the boolean values
+    // truthiness
+    // | ResponseSuccesfull<Succesfull>
+    // | ResponseFailed<Succesfull>;
+    | {
+        status: _Response["status"];
+        msg: _Response["statusText"];
+        ok: true;
+        fail?: false;
+        data: Succesfull;
+      }
+    | {
+        status: _Response["status"];
+        msg: _Response["statusText"];
+        ok?: false;
+        fail: true;
+        data: Failed;
+      };
+
+  type ResponseAdapter = <
+    Succesfull extends DataSuccesfull = DataSuccesfull,
+    Failed extends DataFailed = DataFailed
+  >(
+    response: _Response,
+    options: RequestOptions
+  ) => Promise<Koine.Api.Response<Succesfull, Failed>>;
+
+  //////////////////////////////////////////////////////////////////////////////
+  //
+  // Hooks
+  //
+  //////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Api hooks map for `react`, each request method has its own `use{Method}`
+   * hook.
+   *
+   * These hooks are implemented with different libraries or, in the future as
+   * standalone hooks, see SWR ones to start with.
+   */
+  type HooksMaps = readonly {
+    [TMethod in RequestMethod]: `use${Capitalize<TMethod>}`;
+  };
+
+  type HooksMapsByName = readonly { [K in keyof HooksMaps as HooksMaps[K]]: K };
+}