@biblioteksentralen/bmdb-search 0.0.0-beta.32 → 0.0.0-beta.34

package/README.md

@@ -2,18 +2,104 @@
 
 TypeScript client for searching Bibliotekenes metadatabrønn (BMDB) using [openapi-fetch](https://openapi-ts.dev/openapi-fetch/).
 
-## Usage examples
+## Setup
 
-### Setup client
+### Setup for server-side usage
+
+If the client is running in an environment that can keep secrets, i.e. server-side, the bundled
+`clientCredentialsAccessTokenGetter` helper can be used to exchange your long-lived OAuth 2.0
+client credentials for short-lived access tokens:
+
+```typescript
+import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search/v1";
+import { clientCredentialsAccessTokenGetter } from "@biblioteksentralen/bmdb-search/server";
+
+const bmdbSearchClient = createBmdbFetchClient({
+  host: "https://search.bmdb.no",
+  auth: clientCredentialsAccessTokenGetter({
+    clientId: process.env.BMDB_CORDATA_API_CLIENT_ID,
+    clientSecret: process.env.BMDB_CORDATA_API_CLIENT_SECRET,
+  }),
+});
+```
+
+Note: If you are planning to access pre-production environments, see notes below on how to
+connect to those below.
+
+### Setup for client-side (frontend) usage
+
+To use the BMDB search client in a client-side environment, i.e. one that cannot keep secrets,
+the client needs to fetch access tokens from a server-side route that you manage.
+
+Example:
+
+```typescript
+// clients/bmdbClient.ts
+import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search/v1";
+
+export const bmdbBrowserClient = createBmdbFetchClient({
+  host: "https://search.bmdb.no",
+  auth: async () => {
+    // Fetches access token from an endpoint you manage
+    const response = await fetch("/api/bmdb/access-token");
+
+    if (!response.ok) {
+      throw new Error("Failed to fetch BMDB access token");
+    }
+
+    const { accessToken } = await response.json();
+    return accessToken;
+  },
+});
+```
+
+Note that the client's auth middleware caches tokens in memory, only calling the endpoint when a new
+token is needed. For this reason, it's recommended to not create a new client for each request, but
+reuse it.
+
+The implementation of the server-side API route depends on the programming language and framework
+you use. Below is a simple example for Next.js with App Router:
 
 ```typescript
-import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search";
+// app/api/bmdb/access-token/route.ts
+import { clientCredentialsAccessTokenGetter } from "@biblioteksentralen/bmdb-search/server";
+
+const getAccessToken = clientCredentialsAccessTokenGetter({
+  clientId: process.env.BMDB_CORDATA_API_CLIENT_ID,
+  clientSecret: process.env.BMDB_CORDATA_API_CLIENT_SECRET,
+});
+
+export async function GET() {
+  try {
+    // Ask yourself if you want to restrict clients before returning a token
+    const accessToken = await getAccessToken();
+    return Response.json({ accessToken });
+  } catch (err) {
+    console.error(`Failed to fetch access token`, err);
+    return Response.json({ error: "Failed to fetch access token" }, { status: 500 });
+  }
+}
+```
+
+### Connecting to pre-production environments (dev/test/staging)
+
+When connecting to pre-production environments, the OAuth 2.0 Authorization Server Token URL must be
+be specified manually through the `tokenUrl` parameter. Example for connecting to the test/staging
+environment:
 
+```typescript
 const bmdbSearchClient = createBmdbFetchClient({
-  host: "https://search.bmdb.no/",
+  host: "https://search-staging.bmdb.no",
+  auth: clientCredentialsAccessTokenGetter({
+    clientId: process.env.BMDB_CORDATA_API_CLIENT_ID,
+    clientSecret: process.env.BMDB_CORDATA_API_CLIENT_SECRET,
+    tokenUrl: "https://biblioteksentralen-uat.eu.kinde.com/oauth2/token",
+  }),
 });
 ```
 
+## Usage
+
 ### Search works
 
 ```typescript
@@ -53,26 +139,9 @@ const { data, error } = await bmdbSearchClient.GET("/{searchProfile}/agents/sear
 const { data, error } = await bmdbSearchClient.GET("/{searchProfile}/agents/search", {
   params: {
     path: { searchProfile: "global" },
-    query: { facet: "role", size: 0, facet_terms_size: 20 },
+    query: { facet: ["role"], size: 0, facet_terms_size: 20 },
   },
 });
 ```
 
 The arguments and response are fully typed.
-
-## Usage with Next.js
-
-The queries have to happen in a server context. For this purpose we can create a server client:
-
-```typescript
-"server only";
-
-import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search";
-import { headers } from "next/headers";
-
-export const getBmdbServerFetchClient = async () =>
-  createBmdbFetchClient({
-    host: "https://search.bmdb.no/",
-    headers: await headers(),
-  });
-```