@biblioteksentralen/bmdb-search 0.0.0-beta.7 → 0.0.0-beta.70

package/CHANGELOG.md

@@ -1,3 +1,10 @@
 # @biblioteksentralen/bmdb-search
 
-TODO
+## 0.0.0-beta.16
+
+- [BREAKING] `/{profile}` prefix for all routes
+- Removed `clientIdentifier`
+
+## 0.0.0-beta.14
+
+- Refactored `Work.subjects` model

package/README.md

@@ -2,78 +2,147 @@
 
 TypeScript client for searching Bibliotekenes metadatabrønn (BMDB) using [openapi-fetch](https://openapi-ts.dev/openapi-fetch/).
 
-## Options
+## Setup
 
-### Client identification policy
+### Setup for server-side usage
 
-The API does not require authentication, but clients should identify themselves using a descriptive
-name and a contact address in the `clientIdentifier` string. We will only contact you about usage of the API.
-
-## Usage examples
-
-### Search works
+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";
+import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search/v1";
+import { clientCredentialsAccessTokenGetter } from "@biblioteksentralen/bmdb-search/server";
 
 const bmdbSearchClient = createBmdbFetchClient({
-  clientIdentifier: "client-unique-description",
-  host: "https://search.data.bs.no",
+  host: "https://search.bmdb.no",
+  auth: clientCredentialsAccessTokenGetter({
+    clientId: process.env.BMDB_CORDATA_API_CLIENT_ID,
+    clientSecret: process.env.BMDB_CORDATA_API_CLIENT_SECRET,
+  }),
 });
-const { data, error } = await bmdbSearchClient.GET("/works/search", { params: { query: { query: "test" } } });
 ```
 
-The arguments and response are fully typed.
+Note: If you are planning to access pre-production environments, see notes below on how to
+connect to those below.
 
-### Usage with tanstack-query, openapi-react-query and next.js
+### Setup for client-side (frontend) usage
 
-Using [tanstack](https://tanstack.com/query/latest) for fetching with state management and [openapi-react-query](https://openapi-ts.dev/openapi-react-query/) for typing.
+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.
 
-Add a rewrite in the next.js config file to be able to use the frontend host without violating the content service policy:
+Example:
 
 ```typescript
-// next.config.js or similar
-const searchApiHost = "https://search.data.bs.no";
-
-const config = {
-  // ... other config ...
-  rewrites() {
-    return [
-      {
-        source: "/bmdb/api/:path*",
-        destination: `${searchApiHost}/bmdb/api/:path*`,
-      },
-    ];
+// 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
+// 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, and the audience must be specified through the
+`audience` parameter. Example for connecting to the test/staging environment:
+
+```typescript
+const bmdbSearchClient = createBmdbFetchClient({
+  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",
+    audience: " https://search-staging.bmdb.no/cordata/",
+  }),
+});
 ```
 
-If necessary, skip in middleware to exempt the API paths from internationalization etc:
+## Usage
+
+### Search works
 
 ```typescript
-// middleware.ts
-export const config = {
-  matcher: [
-    // ...other
-    "/((?!|bmdb/api|_next/static).*)",
-  ],
-};
+const { data, error } = await bmdbSearchClient.GET("/{searchProfile}/works/search", {
+  params: {
+    path: { searchProfile: "global" },
+    query: { query: "test" },
+  },
+});
 ```
 
-Create hooks and fetch data:
+### Get works
 
 ```typescript
-import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search";
-import createReactQueryClient from "openapi-react-query";
+const { data, error } = await bmdbSearchClient.GET("/{searchProfile}/works", {
+  params: {
+    path: { searchProfile: "deichman" },
+    query: { ids: "1237715,1237713" },
+  },
+});
+```
 
-const bmdbSearchClient = createBmdbFetchClient({ clientIdentifier: "client-unique-description" });
-const { useQuery } = createReactQueryClient(bmdbSearchClient);
+### Search agents
 
-const Component = () => {
-  const { data, error, isLoading } = useQuery("get", "/works/search", { params: { query: { query: "test" } } });
-  if (isLoading) return <div>Loading</div>;
-  if (error) return <div>Something went wrong</div>;
-  return <div>Found {data?.total} works</div>;
-};
+```typescript
+const { data, error } = await bmdbSearchClient.GET("/{searchProfile}/agents/search", {
+  params: {
+    path: { searchProfile: "tonsberg" },
+    query: { query: "test" },
+  },
+});
+```
+
+### Find all contributor roles for a given agent
 
+```typescript
+const { data, error } = await bmdbSearchClient.GET("/{searchProfile}/agents/search", {
+  params: {
+    path: { searchProfile: "global" },
+    query: { facet: ["role"], size: 0, facet_terms_size: 20 },
+  },
+});
 ```
+
+The arguments and response are fully typed.