@eightyfourthousand/data-access 2026.3.0

package/src/lib/folio.ts

@@ -0,0 +1,43 @@
+'use server';
+
+import { createServerClient } from './client-ssr';
+import { TohokuCatalogEntry } from './types';
+import { FolioDTO, folioFromDTO } from './types/folio';
+
+export const getFolios = async ({
+  uuid,
+  toh,
+  page = 0,
+  size = 10,
+}: {
+  uuid: string;
+  toh: TohokuCatalogEntry;
+  page?: number;
+  size?: number;
+}) => {
+  const start = page * size;
+  const end = start + size - 1;
+  const client = await createServerClient();
+  const { data, error } = await client
+    .from('tibetan_works_folios')
+    .select(
+      `
+      folio_uuid,
+      content::text,
+      volume_number::int4,
+      folio_number::int4,
+      side::text`,
+    )
+    .eq('work_uuid', uuid)
+    .eq('toh', toh)
+    .order('folio_number', { ascending: true })
+    .order('side', { ascending: true })
+    .range(start, end);
+
+  if (error) {
+    console.error('Error fetching folios:', error);
+    return [];
+  }
+
+  return data.map((dto) => folioFromDTO(dto as FolioDTO));
+};

package/src/lib/glossary.ts

@@ -0,0 +1,147 @@
+import {
+  DataClient,
+  GlossaryDetailDTO,
+  GlossaryEntityDTO,
+  GlossaryInstanceDTO,
+  GlossaryTermInstanceDTO,
+  GlossaryLandingItem,
+  GlossaryLandingItemDTO,
+  glossaryTermInstanceFromDTO,
+  glossaryLandingItemFromDTO,
+  glossaryPageItemFromDTO,
+  GlossaryTermInstancesDTO,
+} from './types';
+
+export const getAllGlossaryTerms = async ({
+  client,
+  uuids,
+}: {
+  client: DataClient;
+  uuids?: string[];
+}): Promise<GlossaryLandingItem[]> => {
+  const pageSize = 1000;
+  let start = 0;
+  let end = pageSize - 1;
+  let count = pageSize;
+  const terms: GlossaryLandingItem[] = [];
+
+  while (count === pageSize) {
+    let rpc = client.rpc('scholar_glossary_get_all');
+
+    if (uuids?.length) {
+      rpc = rpc.in('authority_uuid', uuids);
+    }
+
+    const { data, error } = await rpc.range(start, end);
+
+    if (error) {
+      console.error('Error fetching glossary terms:', error);
+      return [];
+    }
+    if (!data || !data.length) {
+      break;
+    }
+
+    const dtos = data as GlossaryLandingItemDTO[];
+    const items = dtos
+      .map((item) => glossaryLandingItemFromDTO(item as GlossaryLandingItemDTO))
+      .flatMap((item) => (item ? [item] : []));
+
+    terms.push(...items);
+    start += pageSize;
+    end += pageSize;
+    count = data.length;
+  }
+
+  return terms;
+};
+
+export const getGlossaryInstances = async ({
+  client,
+  uuid,
+  withAttestations = false,
+}: {
+  client: DataClient;
+  uuid: string;
+  withAttestations?: boolean;
+}) => {
+  const { data, error } = await client.rpc('show_glossary_entries', {
+    v_work_uuid: uuid,
+    v_with_attestation: withAttestations,
+  });
+  if (error) {
+    console.error(
+      `Error fetching glossary instances for work: ${uuid} `,
+      error,
+    );
+    return [];
+  }
+
+  const dto = data as GlossaryTermInstancesDTO;
+  return dto.glossary_entries.map(glossaryTermInstanceFromDTO).sort((a, b) => {
+    const nameA = a.names.english || '';
+    const nameB = b.names.english || '';
+    return nameA.localeCompare(nameB);
+  });
+};
+
+export const getGlossaryInstance = async ({
+  client,
+  uuid,
+}: {
+  client: DataClient;
+  uuid: string;
+}) => {
+  const { data, error } = await client.rpc('show_glossary_entry', {
+    v_glossary_uuid: uuid,
+  });
+
+  if (error) {
+    console.error(`Error fetching glossary instance: ${uuid} `, error);
+    return undefined;
+  }
+
+  return glossaryTermInstanceFromDTO(data as GlossaryTermInstanceDTO);
+};
+
+export const getGlossaryEntry = async ({
+  client,
+  uuid,
+}: {
+  client: DataClient;
+  uuid: string;
+}) => {
+  const { data: details = [], error: detailError } = await client.rpc(
+    'scholar_glossary_detail',
+    { v_uuid: uuid },
+  );
+
+  if (detailError || !details?.length) {
+    console.error('Error fetching glossary item:', detailError);
+    return null;
+  }
+
+  const detail = details[0];
+
+  const { data: entities = [], error: entitiesError } = await client.rpc(
+    'scholar_glossary_detail_related_entities',
+    { v_uuid: uuid },
+  );
+  if (entitiesError) {
+    console.error('Error fetching related entities:', entitiesError);
+  }
+
+  const { data: glossaries = [], error: glossariesError } = await client.rpc(
+    'scholar_glossary_detail_related_glossaries',
+    { v_uuid: uuid },
+  );
+  if (glossariesError) {
+    console.error('Error fetching related glossaries:', glossariesError);
+  }
+
+  return glossaryPageItemFromDTO(
+    detail as GlossaryDetailDTO,
+    glossaries as GlossaryInstanceDTO[],
+    entities as GlossaryEntityDTO[],
+  );
+};

package/src/lib/imprint.ts

@@ -0,0 +1,42 @@
+import { DataClient, imprintFromDTO, tocFromDTO } from './types';
+
+export const getTranslationToc = async ({
+  client,
+  uuid,
+}: {
+  client: DataClient;
+  uuid: string;
+}) => {
+  const { data, error } = await client.rpc('get_work_toc', {
+    work_uuid_input: uuid,
+  });
+
+  if (error) {
+    console.error('Error fetching TOC:', error);
+    return undefined;
+  }
+
+  return tocFromDTO(data || []);
+};
+
+export const getTranslationImprint = async ({
+  client,
+  uuid,
+  toh,
+}: {
+  client: DataClient;
+  uuid: string;
+  toh: string;
+}) => {
+  const { data, error } = await client.rpc('get_imprint', {
+    work_uuid: uuid,
+    toh,
+  });
+
+  if (error || !data) {
+    console.error('Error fetching imprint:', error);
+    return undefined;
+  }
+
+  return imprintFromDTO(data);
+};

package/src/lib/library.ts

@@ -0,0 +1,209 @@
+import {
+  DataClient,
+  LibraryItemType,
+  UserLibraryItem,
+  UserPassageItem,
+} from './types';
+
+export const updateUserProfile = async ({
+  client,
+  userId,
+  avatar,
+  name,
+  username,
+  subscriptions,
+}: {
+  client: DataClient;
+  userId: string;
+  subscriptions: string[];
+  avatar?: string;
+  name?: string;
+  username?: string;
+}): Promise<boolean> => {
+  const { error } = await client
+    .from('user_profiles')
+    .update({
+      avatar_url: avatar,
+      full_name: name,
+      username: username,
+      subscriptions,
+      updated_at: new Date().toISOString(),
+    })
+    .eq('id', userId);
+
+  if (error) {
+    console.error('Error updating user subscriptions:', error);
+    return false;
+  }
+
+  return true;
+};
+
+export const getUserLibrary = async ({
+  client,
+  userId,
+}: {
+  client: DataClient;
+  userId: string;
+}): Promise<UserLibraryItem[]> => {
+  const { data, error } = await client
+    .from('user_libraries')
+    .select(
+      `
+        uuid:entity_id::uuid,
+        type:entity_type::text,
+        createdAt:created_at::text,
+        featured::bool
+      `,
+    )
+    .eq('user_id', userId);
+
+  if (error) {
+    console.error('Error fetching user library:', error);
+    return [];
+  }
+
+  return (data || []) as UserLibraryItem[];
+};
+
+export const addUserLibraryItem = async ({
+  client,
+  userId,
+  type,
+  entityId,
+}: {
+  client: DataClient;
+  userId: string;
+  type: LibraryItemType;
+  entityId: string;
+}): Promise<boolean> => {
+  const { error } = await client.from('user_libraries').insert({
+    user_id: userId,
+    entity_id: entityId,
+    entity_type: type,
+    featured: true,
+  });
+
+  if (error) {
+    console.error('Error adding to user library:', error);
+    return false;
+  }
+
+  return true;
+};
+
+export const removeUserLibraryItem = async ({
+  client,
+  entityId,
+}: {
+  client: DataClient;
+  entityId: string;
+}): Promise<boolean> => {
+  const { error } = await client
+    .from('user_libraries')
+    .delete()
+    .eq('entity_id', entityId);
+
+  if (error) {
+    console.error('Error removing from user library:', error);
+    return false;
+  }
+
+  return true;
+};
+
+export const getUserBibliographies = async ({
+  client,
+  uuids,
+}: {
+  client: DataClient;
+  uuids: string[];
+}) => {
+  const { data, error } = await client
+    .from('bibliographies')
+    .select(
+      `
+      uuid::text,
+      toh::text,
+      text:bibl_text::text
+    `,
+    )
+    .in('uuid', uuids);
+
+  if (error) {
+    console.error('Error fetching user bibliographies:', error);
+    return [];
+  }
+
+  return data || [];
+};
+
+export const getUserPassages = async ({
+  client,
+  uuids,
+}: {
+  client: DataClient;
+  uuids: string[];
+}) => {
+  const { data, error } = await client
+    .from('passages')
+    .select(
+      `
+      uuid::text,
+      content::text,
+      label::text,
+      work:works(
+        toh::text,
+        uuid::text
+      )
+    `,
+    )
+    .in('uuid', uuids);
+  if (error) {
+    console.error('Error fetching user passages:', error);
+    return [];
+  }
+
+  // NOTE: Supabase incorrectly infers `work` as an array. We have to jump
+  // though the hoop of casting to inknown first.
+  return (data || []) as unknown as UserPassageItem[];
+};
+
+export const getUserPublications = async ({
+  client,
+  uuids,
+}: {
+  client: DataClient;
+  uuids: string[];
+}) => {
+  const { data, error } = await client
+    .from('works')
+    .select(
+      `
+      uuid::text,
+      title::text,
+      toh::text,
+      titles(content::text,language::text),
+      sections:catalog_works(...catalogs(label::text))
+    `,
+    )
+    .like('titles.type', '%mainTitle')
+    .in('titles.language', ['bo', 'en'])
+    .in('uuid', uuids);
+
+  if (error) {
+    console.error('Error fetching user publications:', error);
+    return [];
+  }
+
+  return data || [];
+};
+
+export const getUserSearches = async (_: {
+  client: DataClient;
+  uuids: string[];
+}) => {
+  // TODO: Support saving and retrieving user searches
+  console.warn('getUserSearches not implemented yet');
+  return [] as { uuid: string; name: string; query: string }[];
+};

package/src/lib/local-storage.ts

@@ -0,0 +1,33 @@
+export type BookmarkItem = {
+  type: string;
+  subType?: string;
+  tab: string;
+  uuid: string;
+};
+
+const LIBRARY_KEY = 'library';
+
+export function getBookmarks(): BookmarkItem[] {
+  try {
+    const raw = localStorage.getItem(LIBRARY_KEY);
+    if (!raw) return [];
+    return JSON.parse(raw) as BookmarkItem[];
+  } catch {
+    return [];
+  }
+}
+
+export function addBookmark(item: BookmarkItem): void {
+  const bookmarks = getBookmarks().filter((b) => b.uuid !== item.uuid);
+  bookmarks.push(item);
+  localStorage.setItem(LIBRARY_KEY, JSON.stringify(bookmarks));
+}
+
+export function removeBookmark(uuid: string): void {
+  const bookmarks = getBookmarks().filter((b) => b.uuid !== uuid);
+  localStorage.setItem(LIBRARY_KEY, JSON.stringify(bookmarks));
+}
+
+export function isBookmarked(uuid: string): boolean {
+  return getBookmarks().some((b) => b.uuid === uuid);
+}

package/src/lib/lookup-entity.ts

@@ -0,0 +1,122 @@
+import { createServerClient } from './client-ssr';
+import { getBibliographyEntry } from './bibliography';
+import { getPassage, getPassageUuidByXmlId } from './passage';
+import {
+  getTranslationMetadataByToh,
+  getTranslationMetadataByUuid,
+} from './publications';
+import { panelAndTabForContentType } from './panel-url';
+import { getGlossaryInstance } from './glossary';
+
+const ALLOWED_TYPES = ['bibliography', 'glossary', 'passage', 'translation', 'work'];
+
+export const lookupEntity = async ({
+  type,
+  entity,
+  prefix = '',
+  xmlId,
+  searchParams,
+}: {
+  type: string;
+  entity: string;
+  prefix?: string;
+  xmlId?: string;
+  searchParams?: URLSearchParams;
+}) => {
+  if (!ALLOWED_TYPES.includes(type)) {
+    return;
+  }
+  const client = await createServerClient();
+  let path = '';
+  const query = searchParams || new URLSearchParams();
+
+  switch (type) {
+    case 'bibliography':
+      {
+        const item = await getBibliographyEntry({ client, uuid: entity });
+        if (!item?.workUuid || !item.uuid) {
+          return;
+        }
+
+        query.set('right', `open:bibliography:${item.uuid}`);
+        path = `${prefix}/${item.workUuid}?${query.toString()}`;
+      }
+      break;
+    case 'glossary':
+      {
+        const item = await getGlossaryInstance({ client, uuid: entity });
+        if (!item?.workUuid || !item.authority) {
+          return;
+        }
+
+        query.set('right', `open:glossary:${item.authority}`);
+        path = `${prefix}/${item.workUuid}?${query.toString()}`;
+      }
+      break;
+    case 'passage':
+      {
+        const item = await getPassage({ client, uuid: entity });
+        if (!item?.workUuid || !item.uuid) {
+          return;
+        }
+
+        const queryTab = query.get('tab') || undefined;
+        const { panel, tab } = panelAndTabForContentType(item.type, queryTab);
+
+        query.delete('tab');
+        query.set(panel, `open:${tab}:${item.uuid}`);
+        if (item.toh) {
+          query.set('toh', item.toh);
+        }
+
+        path = `${prefix}/${item.workUuid}?${query.toString()}`;
+      }
+      break;
+    case 'translation':
+      {
+        const toh = entity.replace('.html', '');
+        query.set('toh', toh);
+
+        if (xmlId) {
+          const item = await getPassageUuidByXmlId({ client, xmlId });
+          const queryTab = query.get('tab') || undefined;
+          const { panel, tab } = panelAndTabForContentType(item.type, queryTab);
+
+          if (item?.uuid && item?.workUuid) {
+            const { uuid, workUuid } = item;
+            query.delete('tab');
+            query.set(panel, `open:${tab}:${uuid}`);
+
+            path = `${prefix}/${workUuid}?${query.toString()}`;
+            return path;
+          }
+        }
+
+        const item = await getTranslationMetadataByToh({ client, toh });
+        if (!item?.uuid) {
+          return;
+        }
+
+        path = `${prefix}/${item.uuid}?${query.toString()}`;
+      }
+      break;
+    case 'work':
+      {
+        const item = await getTranslationMetadataByUuid({
+          client,
+          uuid: entity,
+        });
+        if (!item?.uuid) {
+          return;
+        }
+
+        path = `${prefix}/${item.uuid}?${query.toString()}`;
+      }
+      break;
+    default: {
+      return;
+    }
+  }
+
+  return path;
+};

package/src/lib/panel-url.ts

@@ -0,0 +1,43 @@
+import {
+  PANEL_FOR_CONTENT_SECTION,
+  PanelContentType,
+  TAB_FOR_CONTENT_SECTION,
+  VARIANT_TABS_FOR_TAB,
+} from './types';
+
+export const panelAndTabForContentType = (
+  contentType: PanelContentType,
+  desiredTab?: string,
+): { panel: string; tab: string } => {
+  const section = contentType.replace('Header', '');
+  const panel = PANEL_FOR_CONTENT_SECTION[section] || 'main';
+  const defaultTab = TAB_FOR_CONTENT_SECTION[section] || 'translation';
+  const variantTabs = VARIANT_TABS_FOR_TAB[section] || [];
+  const tab =
+    desiredTab && variantTabs.includes(desiredTab) ? desiredTab : defaultTab;
+
+  return { panel, tab };
+};
+
+export const urlForPanelContent = ({
+  location,
+  hash,
+  contentType,
+}: {
+  location: Location;
+  hash: string;
+  contentType?: PanelContentType;
+}): string => {
+  const { href, search } = location;
+  const baseUrl = new URL(href);
+  const searchParams = new URLSearchParams(search);
+
+  if (!contentType) {
+    baseUrl.hash = `#${hash}`;
+    return baseUrl.toString();
+  }
+  const { panel, tab } = panelAndTabForContentType(contentType);
+  searchParams.set(panel, `open:${tab}:${hash}`);
+  baseUrl.search = searchParams.toString();
+  return baseUrl.toString();
+};