@servicetitan/docs-uikit 24.3.0 → 25.0.0

package/docs/ajax-handlers.mdx

@@ -0,0 +1,146 @@
+---
+title: AJAX Handlers
+---
+
+import Admonition from '@theme/Admonition';
+import { VersionHistory, Changes } from '@site/src/components/version-history';
+
+<VersionHistory>
+    <Changes forVersion="v25.0.0">
+        <Admonition type="caution" title="Breaking changes">
+            Changed <code>withMicroservice</code> to accept a single options argument.
+        </Admonition>
+    </Changes>
+</VersionHistory>
+
+## withMicroservice
+
+`withMicroservice` is a higher-order function that wraps a component and authenticates
+its requests to protected resources.
+
+### Usage
+
+The best way to use `withMicroservice` is to wrap the component in the ES module body. E.g.,
+
+```tsx
+import { withMicroservice } from '@servicetitan/ajax-handlers';
+
+const UnwrappedApp: FC = () => {
+    ...
+}
+
+const App = withMicroservice({
+    baseURL: '/api',
+    authURL: '/api/auth',
+    component: UnwrappedApp,
+});
+```
+
+If `withMicroservice` is called within another React component, we recommend memoizing
+the return value to avoid performance issues when re-rendering. E.g.,
+
+```tsx
+import { withMicroservice } from '@servicetitan/ajax-handlers';
+
+const UnwrappedApp: FC = () => {
+    ...
+}
+
+const App = () => {
+    const AppWithAuthentication = useMemo(() => {
+        return withMicroservice({
+            baseURL: '/api',
+            authURL: '/api/auth',
+            component: UnwrappedApp,
+        });
+    }, []);
+
+    return (
+        <Provide singletons={[ ... ]}>
+            <AppWithAuthentication />
+        </Provide>
+    )
+}
+```
+
+### Parameters
+
+`withMicroservice` accepts an object with the following properties:
+
+| Name              | Type                                | Description                                                                                                                                                    |
+| :---------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `authAdapter`     | <code>string &#124; Function</code> | (optional) authentication scheme ([see below](#auth-adapter)). Defaults to **Bearer** authentication.                                                          |
+| `authURL`         | `string`                            | (optional) authentication endpoint for protected resources. Value is only optional for **Token** authentication. It is required for **Bearer** authentication. |
+| `baseURL`         | `string`                            | base URL of protected resources                                                                                                                                |
+| `component`       | `React.ComponentType`               | component to wrap                                                                                                                                              |
+| `extraHeaders`    | `Record<string, any>`               | (optional) extra headers to add to requests                                                                                                                    |
+| `preAuthenticate` | `boolean`                           | (optional) whether to authenticate immediately or wait for the first request. Defaults to `false`.                                                             |
+| `tokens`          | `Symbol[]`                          | (optional) symbols to use to provide `baseURL` to autogenerated API services and child components                                                              |
+
+#### authAdapter{#auth-adapter}
+
+Use `authAdapter` to select the authentication scheme. One of,
+
+| Value        | Description                                                                                                         |
+| :----------- | :------------------------------------------------------------------------------------------------------------------ |
+| "bearer"     | **Bearer** authentication sends the bearer token returned by `authURL` in the **Authorization** header of requests. |
+| "token"      | **Token** authentication uses the Token Server's "silent login" protocol to add secure cookies to requests.         |
+| `<Function>` | Custom authentication uses the adapter returned by `Function` to decorate requests.                                 |
+
+#### authUrl
+
+The authentication endpoint for protected resources.
+
+-   For **Bearer** authentication, this is the endpoint that returns the bearer token to send in **Authorization** headers.
+
+-   For **Token server** authentication, this the "silent login" endpoint. Defaults to `${baseURL}/bff/silent-login`.
+
+#### preAuthenticate
+
+Controls when authentication happens:
+
+| Value   | Description                                                                    |
+| :------ | :----------------------------------------------------------------------------- |
+| `false` | Wait for the first request to a protected resource. This is the default value. |
+| `true`  | Authenticate immediately after the component is loaded                         |
+
+#### tokens
+
+The main purpose of `tokens` is to [provide](./react-ioc#provide) the `baseURL` to autogenerated API services.
+For example,
+
+```tsx
+import { BASE_URL_TOKEN_ArcGisApi, BASE_URL_TOKEN_AudiencesApi } from '@servicetitan/marketing-audience-api';
+
+const MarketingWithMicroservice = withMicroservice({
+    component: Marketing,
+    tokens: [BASE_URL_TOKEN_ArcGisApi, BASE_URL_TOKEN_AudiencesApi],
+    ...
+});
+```
+
+You can also use `tokens` to pass the `baseURL` value to any child component. E.g.,
+
+```tsx
+const MY_BASE_URL_TOKEN = symbolToken<string>('MY_BASE_URL_TOKEN');
+
+withMicroservice({ tokens: [MY_BASE_URL_TOKEN], ... });
+```
+
+And in the child component,
+
+```tsx
+import { symbolToken, useDependencies } from '@servicetitan/react-ioc';
+
+const MY_BASE_URL_TOKEN = symbolToken<string>('MY_BASE_URL_TOKEN');
+
+const Component = () => {
+    const [baseURL] = useDependencies(MY_BASE_URL_TOKEN);
+
+    ...
+}
+```
+
+### Authorization
+
+`withMicroservice` currently only assists with performing authentication for requests of protected resources. There are currently no plans to implement authorization until we see concrete Token Server usage examples by product teams. If you find that having any sort of implementation for authorization would be helpful, especially in regards to Token Server implementation, please bring any ideas or discussions to the Frontend Platform team's attention so that we can create a platform solution.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "24.3.0",
+    "version": "25.0.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "803b8c55ef25da60f99a663d0629d281f0ad50dd"
+    "gitHead": "db04847b5e4d8f0e679ce6c6f561aab10ade927d"
 }