@biblioteksentralen/bmdb-search 0.0.0-beta.6 → 0.0.0-beta.8

package/README.md

@@ -6,8 +6,7 @@ TypeScript client for searching Bibliotekenes metadatabrønn (BMDB) using [opena
 
 ### Client identification policy
 
-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.
+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
 
@@ -16,54 +15,29 @@ name and a contact address in the `clientIdentifier` string. We will only contac
 ```typescript
 import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search";
 
-const bmdbSearchClient = createBmdbFetchClient({ clientIdentifier: "client-unique-description" });
+const bmdbSearchClient = createBmdbFetchClient({
+  clientIdentifier: "client-unique-description",
+  host: "https://search.data.bs.no",
+});
+
 const { data, error } = await bmdbSearchClient.GET("/works/search", { params: { query: { query: "test" } } });
 ```
 
 The arguments and response are fully typed.
 
-### Usage with tanstack-query, openapi-react-query and next.js
+### Usage with tanstack-query, openapi-react-query and React hooks
 
 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.
 
-Add a rewrite in the next.js config file to be able to use the frontend host without violating the content service policy:
-
-```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*`,
-      },
-    ];
-  },
-};
-```
-
-If necessary, skip in middleware to exempt the API paths from internationalization etc:
-
-```typescript
-// middleware.ts
-export const config = {
-  matcher: [
-    // ...other
-    "/((?!|bmdb/api|_next/static).*)",
-  ],
-};
-```
-
-Create hooks and fetch data:
-
 ```typescript
 import { createBmdbFetchClient } from "@biblioteksentralen/bmdb-search";
 import createReactQueryClient from "openapi-react-query";
 
-const bmdbSearchClient = createBmdbFetchClient({ clientIdentifier: "client-unique-description" });
+const bmdbSearchClient = createBmdbFetchClient({
+  clientIdentifier: "client-unique-description",
+  host: "https://search.data.bs.no"
+});
+
 const { useQuery } = createReactQueryClient(bmdbSearchClient);
 
 const Component = () => {

package/dist/index.cjs

@@ -19,10 +19,16 @@ var formatSingleTitle = ({ mainTitle, subtitle, partNumber, partTitle }, options
 var formatUniformTitleMusic = ({ form, instrumentation, serialNumber, opusNumber, thematicCatalogueNumber, part, key, arrangement }) => form + (instrumentation ? ` ${instrumentation}` : "") + (serialNumber ? `, ${serialNumber}` : "") + (opusNumber ? `, ${opusNumber}` : "") + (thematicCatalogueNumber ? `, ${thematicCatalogueNumber}` : "") + (part ? `, ${part}` : "") + (key ? `, ${key}` : "") + (arrangement ? `, ${arrangement}` : "");
 var createBmdbFetchClient = ({
   clientIdentifier,
+  host,
   version = "v1",
   ...options
 }) => {
-  const baseUrl = `${options.baseUrl?.replace(/(.*)\/$/, "$1") ?? ""}/bmdb/api/${version}/`;
+  try {
+    new URL(host);
+  } catch {
+    throw new Error(`Invalid host URL: ${host}. The URL must be fully qualified with protocol.`);
+  }
+  const baseUrl = `${host.replace(/(.*)\/$/, "$1")}/bmdb/api/${version}/`;
   const client = createFetchClient__default.default({
     baseUrl,
     querySerializer: { array: { style: "form", explode: false } },

package/dist/index.d.cts

@@ -26,6 +26,27 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/entities/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search entities
+         * @description Endpoint for searching BMDB entites. Implemented: agents.
+         *
+         */
+        get: operations["searchEntities"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface components {
     schemas: {
@@ -1084,6 +1105,52 @@ interface components {
             advancedQueryErrors?: components["schemas"]["AdvanvedQueryError"][];
             sorting: components["schemas"]["WorkSort"];
         };
+        /**
+         * @description Facet type, this is the value given to the search facet parameter. The facet should always exists in as a corresponding filter.
+         *
+         * @enum {string}
+         */
+        EntityFacetType: "agent.nationality";
+        /**
+         * @description Sorting type, this is the value given to the search facet parameter.
+         *
+         * @enum {string}
+         */
+        EntitySort: "relevance.desc" | "updateTime.desc" | "updateTime.asc";
+        EntityFilter: {
+            /** @enum {string} */
+            "type"?: "agent" | "place";
+            "identifier"?: string;
+            "agent.id"?: string;
+            "agent.noraf_id"?: string;
+            "agent.bokbasen_id"?: string;
+            "agent.isni_id"?: string;
+        };
+        EntityFacet: {
+            type: components["schemas"]["EntityFacetType"];
+            /** @description A displayable (human readable) facet name. */
+            name?: string;
+            terms: components["schemas"]["FacetTerm"][];
+        };
+        GetEntitySearch200Response: {
+            /** @description The total number of results in the whole search result. */
+            total?: number;
+            results: {
+                entity?: components["schemas"]["Person"] | components["schemas"]["CollectiveAgent"] | components["schemas"]["Place"];
+            }[];
+            /** @description If this is false, we haven't reached the end of the search result yet, if it's false we have, and if it's missing or null we don't know. */
+            endOfResults: boolean;
+            /** @description This array contains the requested facets, and their terms. Each facet type should only appear once in the array. */
+            facets?: components["schemas"]["EntityFacet"][];
+            /**
+             * @description Indicates what kind of search was performed, based on parsed input query.
+             * @enum {string}
+             */
+            queryType?: "empty" | "standard" | "advanced";
+            /** @description Parsing errors from advanced query. When they occur, the request is treated as a standard search. */
+            advancedQueryErrors?: components["schemas"]["AdvanvedQueryError"][];
+            sorting: components["schemas"]["EntitySort"];
+        };
     };
     responses: never;
     parameters: never;
@@ -1102,10 +1169,10 @@ interface operations {
                  *     This is important to consider in any product design.
                  *      */
                 size?: number;
-                /** @description Page number (deafult 1). */
+                /** @description Page number (default 1). */
                 page?: number;
                 facet?: components["schemas"]["WorkFacetType"][];
-                /** @description Retun this number of facet terms for each requested facet (deafult 10). */
+                /** @description Retun this number of facet terms for each requested facet (default 10). */
                 facet_terms_size?: number;
                 /** @description Sorting */
                 sort?: components["schemas"]["WorkSort"];
@@ -1131,6 +1198,45 @@ interface operations {
             };
         };
     };
+    searchEntities: {
+        parameters: {
+            query?: {
+                /** @description The search query. */
+                query?: string;
+                /** @description Page size (default 10).
+                 *     It's important to be aware that, the page size here is only a preferred page size, the result set can be both small and greater, depending on the implementation from the LMS provider.
+                 *     This is important to consider in any product design.
+                 *      */
+                size?: number;
+                /** @description Page number (default 1). */
+                page?: number;
+                facet?: components["schemas"]["EntityFacetType"][];
+                /** @description Retun this number of facet terms for each requested facet (default 10). */
+                facet_terms_size?: number;
+                /** @description Sorting */
+                sort?: components["schemas"]["EntitySort"];
+                /** @description Each filter accepts multiple comma-separated values that are OR'ed together.
+                 *     The filters themselves are AND'ed together.
+                 *      */
+                filter?: components["schemas"]["EntityFilter"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List of entities */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetEntitySearch200Response"];
+                };
+            };
+        };
+    };
 }
 
 type BmdbApiSchemas$1 = components["schemas"];
@@ -1151,10 +1257,11 @@ type BmdbApiPaths = paths;
 
 type BmdbSearchClientOptions = ClientOptions & {
     clientIdentifier: string;
+    host: string;
     version?: "v1";
 };
 type BmdbSearchClient = Client<BmdbApiPaths>;
-declare const createBmdbFetchClient: ({ clientIdentifier, version, ...options }: BmdbSearchClientOptions) => BmdbSearchClient;
+declare const createBmdbFetchClient: ({ clientIdentifier, host, version, ...options }: BmdbSearchClientOptions) => BmdbSearchClient;
 
 type BmdbWork = BmdbApiSchemas["Work"];
 type BmdbExpression = BmdbApiSchemas["Expression"];

package/dist/index.d.ts

@@ -26,6 +26,27 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/entities/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search entities
+         * @description Endpoint for searching BMDB entites. Implemented: agents.
+         *
+         */
+        get: operations["searchEntities"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 interface components {
     schemas: {
@@ -1084,6 +1105,52 @@ interface components {
             advancedQueryErrors?: components["schemas"]["AdvanvedQueryError"][];
             sorting: components["schemas"]["WorkSort"];
         };
+        /**
+         * @description Facet type, this is the value given to the search facet parameter. The facet should always exists in as a corresponding filter.
+         *
+         * @enum {string}
+         */
+        EntityFacetType: "agent.nationality";
+        /**
+         * @description Sorting type, this is the value given to the search facet parameter.
+         *
+         * @enum {string}
+         */
+        EntitySort: "relevance.desc" | "updateTime.desc" | "updateTime.asc";
+        EntityFilter: {
+            /** @enum {string} */
+            "type"?: "agent" | "place";
+            "identifier"?: string;
+            "agent.id"?: string;
+            "agent.noraf_id"?: string;
+            "agent.bokbasen_id"?: string;
+            "agent.isni_id"?: string;
+        };
+        EntityFacet: {
+            type: components["schemas"]["EntityFacetType"];
+            /** @description A displayable (human readable) facet name. */
+            name?: string;
+            terms: components["schemas"]["FacetTerm"][];
+        };
+        GetEntitySearch200Response: {
+            /** @description The total number of results in the whole search result. */
+            total?: number;
+            results: {
+                entity?: components["schemas"]["Person"] | components["schemas"]["CollectiveAgent"] | components["schemas"]["Place"];
+            }[];
+            /** @description If this is false, we haven't reached the end of the search result yet, if it's false we have, and if it's missing or null we don't know. */
+            endOfResults: boolean;
+            /** @description This array contains the requested facets, and their terms. Each facet type should only appear once in the array. */
+            facets?: components["schemas"]["EntityFacet"][];
+            /**
+             * @description Indicates what kind of search was performed, based on parsed input query.
+             * @enum {string}
+             */
+            queryType?: "empty" | "standard" | "advanced";
+            /** @description Parsing errors from advanced query. When they occur, the request is treated as a standard search. */
+            advancedQueryErrors?: components["schemas"]["AdvanvedQueryError"][];
+            sorting: components["schemas"]["EntitySort"];
+        };
     };
     responses: never;
     parameters: never;
@@ -1102,10 +1169,10 @@ interface operations {
                  *     This is important to consider in any product design.
                  *      */
                 size?: number;
-                /** @description Page number (deafult 1). */
+                /** @description Page number (default 1). */
                 page?: number;
                 facet?: components["schemas"]["WorkFacetType"][];
-                /** @description Retun this number of facet terms for each requested facet (deafult 10). */
+                /** @description Retun this number of facet terms for each requested facet (default 10). */
                 facet_terms_size?: number;
                 /** @description Sorting */
                 sort?: components["schemas"]["WorkSort"];
@@ -1131,6 +1198,45 @@ interface operations {
             };
         };
     };
+    searchEntities: {
+        parameters: {
+            query?: {
+                /** @description The search query. */
+                query?: string;
+                /** @description Page size (default 10).
+                 *     It's important to be aware that, the page size here is only a preferred page size, the result set can be both small and greater, depending on the implementation from the LMS provider.
+                 *     This is important to consider in any product design.
+                 *      */
+                size?: number;
+                /** @description Page number (default 1). */
+                page?: number;
+                facet?: components["schemas"]["EntityFacetType"][];
+                /** @description Retun this number of facet terms for each requested facet (default 10). */
+                facet_terms_size?: number;
+                /** @description Sorting */
+                sort?: components["schemas"]["EntitySort"];
+                /** @description Each filter accepts multiple comma-separated values that are OR'ed together.
+                 *     The filters themselves are AND'ed together.
+                 *      */
+                filter?: components["schemas"]["EntityFilter"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List of entities */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetEntitySearch200Response"];
+                };
+            };
+        };
+    };
 }
 
 type BmdbApiSchemas$1 = components["schemas"];
@@ -1151,10 +1257,11 @@ type BmdbApiPaths = paths;
 
 type BmdbSearchClientOptions = ClientOptions & {
     clientIdentifier: string;
+    host: string;
     version?: "v1";
 };
 type BmdbSearchClient = Client<BmdbApiPaths>;
-declare const createBmdbFetchClient: ({ clientIdentifier, version, ...options }: BmdbSearchClientOptions) => BmdbSearchClient;
+declare const createBmdbFetchClient: ({ clientIdentifier, host, version, ...options }: BmdbSearchClientOptions) => BmdbSearchClient;
 
 type BmdbWork = BmdbApiSchemas["Work"];
 type BmdbExpression = BmdbApiSchemas["Expression"];

package/dist/index.js

@@ -13,10 +13,16 @@ var formatSingleTitle = ({ mainTitle, subtitle, partNumber, partTitle }, options
 var formatUniformTitleMusic = ({ form, instrumentation, serialNumber, opusNumber, thematicCatalogueNumber, part, key, arrangement }) => form + (instrumentation ? ` ${instrumentation}` : "") + (serialNumber ? `, ${serialNumber}` : "") + (opusNumber ? `, ${opusNumber}` : "") + (thematicCatalogueNumber ? `, ${thematicCatalogueNumber}` : "") + (part ? `, ${part}` : "") + (key ? `, ${key}` : "") + (arrangement ? `, ${arrangement}` : "");
 var createBmdbFetchClient = ({
   clientIdentifier,
+  host,
   version = "v1",
   ...options
 }) => {
-  const baseUrl = `${options.baseUrl?.replace(/(.*)\/$/, "$1") ?? ""}/bmdb/api/${version}/`;
+  try {
+    new URL(host);
+  } catch {
+    throw new Error(`Invalid host URL: ${host}. The URL must be fully qualified with protocol.`);
+  }
+  const baseUrl = `${host.replace(/(.*)\/$/, "$1")}/bmdb/api/${version}/`;
   const client = createFetchClient({
     baseUrl,
     querySerializer: { array: { style: "form", explode: false } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biblioteksentralen/bmdb-search",
-  "version": "0.0.0-beta.6",
+  "version": "0.0.0-beta.8",
   "private": false,
   "type": "module",
   "description": "Client for searching Bibliotekenes metadatabrønn (BMDB)",