@newfold/huapi-js 0.1.0-beta.59

package/README.md

@@ -0,0 +1,83 @@
+# @newfold/huapi-js
+
+> A JavaScript Client Library for HUAPI
+
+## Installation
+
+```sh
+$ yarn add @newfold/huapi-js
+# yarn package installed
+```
+
+## Usage
+
+### React Hooks
+
+```js
+import React from 'react';
+
+import { useHostingSites } from '@newfold/huapi-js';
+
+const MyComponent = () => {
+  const hostingId = '2';
+  const { isLoading, data } = useHostingSites(hostingId);
+
+  if (isLoading) return <h1>Loading...</h1>;
+
+  return (
+    <div>
+      {data?.data?.rows?.map((site) => {
+        <div key={site.id}>{site.name}</div>;
+      })}
+    </div>
+  );
+};
+```
+
+### Mocking with custom handlers
+
+Custom [Mock Service Worker](https://mswjs.io/) handlers can be imported directly from `@newfold/huapi-js` to easily manipulate your local application or unit tests in an offline testing setting.
+
+First, ensure that [Mock Service Worker](https://mswjs.io/) is configured in your project, then import and add handlers during your `setupWorker` or `setupServer` calls as follows:
+
+```js
+// import handlers to override data as needed for testing
+import { getHostingSitesHandler } from '@newfold/huapi-js/src/handlers';
+
+// add the handlers to your setupServer call
+const server = setupServer(
+  ...[
+    // mock GET /hosting/:hosting-id/sites
+    getHostingSitesHandler(),
+
+    // add additional handlers here:
+    // postHostingSite(),
+  ]
+);
+```
+
+#### Advanced handlers
+
+## Building from huapi
+
+Eventually we would like to have an automatic CICD pipeline that kicks off when new `huapi` builds change the openapi.json specification file (OAS). For now, we can do this manually by running the build command locally and publishing to npm. This can be done with the following steps:
+
+1. Ensure your repo is on the `main` branch and in a clean state locally (no unstaged changes)
+2. Run `yarn build` to pull down the OAS and create new build files
+3. Publish to npm with `yarn publish --public` [or to use `npm` first manually update the version in package.json and git commit/push this change, then use `npm publish --access public` to publish the changes]
+
+   > NOTE: You may need to request permissions to publish to the npm registry. Please speak to your manager to request access for this through the Hosting Engineering Leadership Team. Please provide your npmjs.com username with your request, and ensure 2FA Authentication is enabled in your npmjs.com dashboard.
+
+## Development
+
+### Adding Endpoints
+
+`@newfold/haupi-js` is based on the OpenAPI specification file that is published by the core `huapi` project. To add new endpoints, update the core project and publish an updated file, then ensure the build script in `package.json` is pointed to it.
+
+```sh
+# run the build command to build a new verions
+$ yarn build
+# building @newfold/huapi-js...
+```
+
+### Adding Custom Mock Handlers

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@newfold/huapi-js",
+  "version": "0.1.0-beta.59",
+  "peerDependencies": {
+    "@faker-js/faker": "^6.1.2",
+    "axios": "^0.27.2",
+    "msw": "^0.42.1",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-query": "^3.39.1",
+    "tslib": "^2.3.0"
+  },
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "dependencies": {}
+}

package/src/handlers.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/handlers';
+export * from './orval-generated/index.msw';

package/src/handlers.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// export custom handlers
+tslib_1.__exportStar(require("./lib/handlers"), exports);
+// export orval-generated handlers
+tslib_1.__exportStar(require("./orval-generated/index.msw"), exports);

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './orval-generated';

package/src/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// export orval-generated
+tslib_1.__exportStar(require("./orval-generated"), exports);

package/src/lib/handlers/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * NOTE: this will move to @newfold/huapi-js in the future
+ * Usage: `import { getHostingSitesHandler } from '@newfold/huapi-js';`
+ */
+export * from './sites/getHostingSitesHandler';

package/src/lib/handlers/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * NOTE: this will move to @newfold/huapi-js in the future
+ * Usage: `import { getHostingSitesHandler } from '@newfold/huapi-js';`
+ */
+tslib_1.__exportStar(require("./sites/getHostingSitesHandler"), exports);

package/src/lib/handlers/sites/data/sites.d.ts

@@ -0,0 +1,19 @@
+export declare const getResponseByStatus: (responseKey: string, status: number) => {
+    message: string;
+    limit?: undefined;
+    n_pages?: undefined;
+    n_rows?: undefined;
+    page?: undefined;
+    rows?: undefined;
+} | {
+    limit: number;
+    n_pages: number;
+    n_rows: number;
+    page: number;
+    rows: {
+        id: string;
+        name: string;
+        url: string;
+    }[];
+    message?: undefined;
+};

package/src/lib/handlers/sites/data/sites.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getResponseByStatus = void 0;
+const rows = [
+    {
+        id: '1',
+        name: 'Site 1',
+        url: 'https://site-1.com',
+    },
+    {
+        id: '2',
+        name: 'Site 2',
+        url: 'https://site-2.com',
+    },
+    {
+        id: '3',
+        name: 'Site 3',
+        url: 'https://site-3.com',
+    },
+    {
+        id: '4',
+        name: 'Site 4',
+        url: 'https://site-4.com',
+    },
+    {
+        id: '5',
+        name: 'Site 5',
+        url: 'https://site-5.com',
+    },
+    {
+        id: '6',
+        name: 'Site 6',
+        url: 'https://site-6.com',
+    },
+    {
+        id: '7',
+        name: 'Site 7',
+        url: 'https://site-7.com',
+    },
+    {
+        id: '8',
+        name: 'Site 8',
+        url: 'https://site-8.com',
+    },
+    {
+        id: '9',
+        name: 'Site 9',
+        url: 'https://site-9.com',
+    },
+    {
+        id: '10',
+        name: 'Site 10',
+        url: 'https://site-10.com',
+    },
+];
+const getResponseByStatus = (responseKey, status) => {
+    switch (status) {
+        case 500 - 599:
+            return {
+                message: 'Something went wrong',
+            };
+        case 200 - 299:
+        default:
+            switch (responseKey) {
+                case '0':
+                    return {
+                        limit: 10,
+                        n_pages: 0,
+                        n_rows: 0,
+                        page: 1,
+                        rows: [],
+                    };
+                case '1':
+                    return {
+                        limit: 10,
+                        n_pages: 1,
+                        n_rows: 1,
+                        page: 1,
+                        rows: [rows[0]],
+                    };
+                default:
+                case 'some':
+                    return {
+                        limit: 10,
+                        n_pages: 1,
+                        n_rows: 3,
+                        page: 1,
+                        rows,
+                    };
+                case 'many':
+                    return {
+                        limit: 10,
+                        n_pages: 50,
+                        n_rows: 3,
+                        page: 1,
+                        rows: [
+                            ...rows,
+                            {
+                                id: '11',
+                                name: 'Site 11',
+                                url: 'https://site-11.com',
+                            },
+                            {
+                                id: '12',
+                                name: 'Site 12',
+                                url: 'https://site-12.com',
+                            },
+                            {
+                                id: '13',
+                                name: 'Site 13',
+                                url: 'https://site-13.com',
+                            },
+                            {
+                                id: '14',
+                                name: 'Site 14',
+                                url: 'https://site-14.com',
+                            },
+                            {
+                                id: '15',
+                                name: 'Site 15',
+                                url: 'https://site-15.com',
+                            },
+                            {
+                                id: '16',
+                                name: 'Site 16',
+                                url: 'https://site-16.com',
+                            },
+                            {
+                                id: '17',
+                                name: 'Site 17',
+                                url: 'https://site-17.com',
+                            },
+                            {
+                                id: '18',
+                                name: 'Site 18',
+                                url: 'https://site-18.com',
+                            },
+                            {
+                                id: '19',
+                                name: 'Site 19',
+                                url: 'https://site-19.com',
+                            },
+                            {
+                                id: '20',
+                                name: 'Site 20',
+                                url: 'https://site-20.com',
+                            },
+                            {
+                                id: '21',
+                                name: 'Site 21',
+                                url: 'https://site-21.com',
+                            },
+                            {
+                                id: '22',
+                                name: 'Site 22',
+                                url: 'https://site-22.com',
+                            },
+                            {
+                                id: '23',
+                                name: 'Site 23',
+                                url: 'https://site-23.com',
+                            },
+                            {
+                                id: '24',
+                                name: 'Site 24',
+                                url: 'https://site-24.com',
+                            },
+                            {
+                                id: '25',
+                                name: 'Site 25',
+                                url: 'https://site-25.com',
+                            },
+                        ],
+                    };
+            }
+    }
+};
+exports.getResponseByStatus = getResponseByStatus;

package/src/lib/handlers/sites/getHostingSitesHandler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * getHostingSitesHandler
+ * @param {string} responseKey - the key of the response to return from the responses object
+ * @param {int} status - the status code to mock
+ * @param {int} delay - the delay in ms to wait before returning the response
+ * @returns - a msw handler
+ */
+export declare function getHostingSitesHandler(responseKey?: string, // int or string
+status?: number, delay?: number): import("msw").RestHandler<import("msw/lib/glossary-58eca5a8").M<import("msw/lib/glossary-58eca5a8").c>>;

package/src/lib/handlers/sites/getHostingSitesHandler.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHostingSitesHandler = void 0;
+const msw_1 = require("msw");
+const sites_1 = require("./data/sites");
+/**
+ * getHostingSitesHandler
+ * @param {string} responseKey - the key of the response to return from the responses object
+ * @param {int} status - the status code to mock
+ * @param {int} delay - the delay in ms to wait before returning the response
+ * @returns - a msw handler
+ */
+function getHostingSitesHandler(responseKey = '1', // int or string
+status = 200, delay = 1000) {
+    return msw_1.rest.get('*/v1/hosting/:hostingId/sites', (req, res, ctx) => res(ctx.delay(delay), ctx.status(status, 'Mocked status'), ctx.json((0, sites_1.getResponseByStatus)(responseKey, status))));
+}
+exports.getHostingSitesHandler = getHostingSitesHandler;