@biblioteksentralen/media-store-api-client

Installation

npm install @biblioteksentralen/media-store-api-client

Note that the package is a pure ESM package and doesn't provide a CommonJS export.

Machine-to-machine usage (backend/NodeJS)

With machine-to-machine (M2M) applications, such as scheduled jobs, where there is no user involved, the application can be authenticated and authorized using the Oauth Client Credentials Flow using the included clientCredentialsMiddleware:

import {
  createMediaStoreApiClient,
  clientCredentialsMiddleware,
} from "@biblioteksentralen/media-store-api-client";

const mediaStore = createMediaStoreApiClient({
  baseUrl: "http://localhost:5000/api/",
  userAgent: "my-little-script",
  auth: clientCredentialsMiddleware({
    tokenUrl: "https://biblioteksentralen-dev.eu.auth0.com/oauth/token",
    clientId: MEDIA_STORE_CLIENT_ID,
    clientSecret: MEDIA_STORE_CLIENT_SECRET,
    audience: "https://media.aja-test.bibsent.dev/",
  }),
});

const { data, error } = await mediaStore.listAssets();

Browser usage

In browsers, an access token for a user can be obtained using Oauth Authorization Code Flow (best) or Implicit Flow (less secure). After logging in the user, obtain an access token and initialize the client with it:

import {
  createMediaStoreApiClient,
  clientCredentialsMiddleware,
} from "@biblioteksentralen/media-store-api-client";

const mediaStore = createMediaStoreApiClient({
  baseUrl: "http://localhost:5000/api/",
  userAgent: "my-little-script",
  auth: accessTokenMiddleware({
    accessToken: MEDIA_STORE_ACCESS_TOKEN,
  }),
});

Error handling

The client returns errors on non-2XX responses. In addition, fetch will throw TypeError on network errors and the clientCredentialsMiddleware will throw FetchAccessTokenError if it cannot obtain an access token. A comprehensive error handling example:

import { FetchAccessTokenError } from "@biblioteksentralen/media-store-api-client";

async function handleApiErrors<Data, Err>(
  request: Promise<
    | {
        data: Data;
        error?: never;
      }
    | {
        data?: never;
        error: Err;
      }
  >,
): Promise<{ data?: Data; error?: { message: string } }> {
  try {
    const { data, error } = await request;
    if (error) {
      return { error: { message: JSON.stringify(error) } };
    }
    return { data };
  } catch (error: unknown) {
    if (error instanceof TypeError) {
      return { error: { message: "Request failed with network error" } };
    } else if (error instanceof FetchAccessTokenError) {
      return { error: { message: "Failed to authenticate" } };
    } else {
      return { error: { message: "Request failed with unknown error" } };
    }
  }
}

const { data, error } = await handleApiErrors(mediaStore.listAssets());
if (error) {
  console.error(error);
} else {
  console.info(data);
}

Example: React hook with SWR

export const useApi = () => {
  const { session } = useSession();
  return useMemo(
    () =>
      session.accessToken
        ? createMediaStoreApiClient({
            baseUrl: "https://media.aja.bs.no/api",
            userAgent: "media-store-manage",
            auth: accessTokenMiddleware({
              accessToken: `Bearer ${session.accessToken}`,
            }),
          })
        : undefined,
    [session.accessToken],
  );
};

export const useListAssets = (query: string) => {
  const api = useApi();
  return useSWR(`listAssets:${query}`, () =>
    api?.listAssets(query ? { ean: query } : undefined),
  );
};