@newfold/huapi-js 1.4.1 → 1.378.0

package/README.md

@@ -1,11 +1,84 @@
-# huapi-js
+# @newfold/huapi-js
 
-This library was generated with [Nx](https://nx.dev).
+> A JavaScript Client Library for HUAPI
 
-## Building
+## Installation
 
-Run `nx build huapi-js` to build the library.
+```sh
+$ yarn add @newfold/huapi-js
+# yarn package installed
+```
 
-## Running unit tests
+## Usage
 
-Run `nx test huapi-js` to execute the unit tests via [Jest](https://jestjs.io).
+### 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 `nx build huapi-js` to pull down the OAS file from the beta server (requires VPN) and create new build files
+3. Change current directory to `./dist/libs/huapi-js`
+4. Publish to npm with `yarn publish --access 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

@@ -1,15 +1,15 @@
 {
   "name": "@newfold/huapi-js",
-  "version": "1.4.1",
   "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"
+    "tslib": "2.4.0"
   },
+  "version": "1.378.0",
   "main": "./src/index.js",
-  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts",
   "dependencies": {}
 }