@eightyfourthousand/client-graphql 2026.3.0

package/src/lib/functions/get-translation-passages.ts

@@ -0,0 +1,168 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type {
+  BodyItemType,
+  PaginationDirection,
+  PassagesPage,
+} from '@eightyfourthousand/data-access';
+import { passagesPageFromGraphQL } from '../mappers';
+
+const GET_PASSAGES = gql`
+  fragment AnnotationFields on Annotation {
+    uuid
+    type
+    start
+    end
+    metadata
+  }
+
+  fragment AlignmentFields on Alignment {
+    folioUuid
+    toh
+    tibetan
+    folioNumber
+    volumeNumber
+  }
+
+  fragment PassageWithAnnotations on Passage {
+    uuid
+    workUuid
+    content
+    label
+    sort
+    type
+    xmlId
+    annotations {
+      ...AnnotationFields
+    }
+    alignments {
+      ...AlignmentFields
+    }
+  }
+
+  query GetPassages(
+    $uuid: ID!
+    $cursor: String
+    $limit: Int
+    $direction: PaginationDirection
+    $filter: PassageFilter
+  ) {
+    work(uuid: $uuid) {
+      uuid
+      passages(
+        cursor: $cursor
+        limit: $limit
+        direction: $direction
+        filter: $filter
+      ) {
+        nodes {
+          ...PassageWithAnnotations
+        }
+        pageInfo {
+          nextCursor
+          prevCursor
+          hasMoreAfter
+          hasMoreBefore
+        }
+      }
+    }
+  }
+`;
+
+type GetPassagesResponse = {
+  work: {
+    uuid: string;
+    passages: {
+      nodes: Array<{
+        uuid: string;
+        workUuid: string;
+        content: string;
+        label: string;
+        sort: number;
+        type: string;
+        xmlId?: string | null;
+        annotations: Array<{
+          uuid: string;
+          type: string;
+          start: number;
+          end: number;
+          metadata?: Record<string, unknown> | null;
+        }>;
+        alignments: Array<{
+          folioUuid: string;
+          toh: string;
+          tibetan: string;
+          folioNumber: number;
+          volumeNumber: number;
+        }>;
+      }>;
+      pageInfo: {
+        nextCursor?: string | null;
+        prevCursor?: string | null;
+        hasMoreAfter: boolean;
+        hasMoreBefore: boolean;
+      };
+    };
+  } | null;
+};
+
+/**
+ * Map internal pagination direction to GraphQL enum
+ */
+function mapDirection(
+  direction?: PaginationDirection,
+): 'FORWARD' | 'BACKWARD' | undefined {
+  if (!direction) return undefined;
+  return direction === 'forward' ? 'FORWARD' : 'BACKWARD';
+}
+
+/**
+ * Get paginated passages for a translation work.
+ *
+ * NOTE: maxCharacters is not supported by the GraphQL API yet.
+ * This parameter is accepted for API compatibility but is ignored.
+ */
+export async function getTranslationPassages({
+  client,
+  uuid,
+  type,
+  cursor,
+  maxPassages = 100,
+  maxCharacters: _maxCharacters,
+  direction,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  type?: BodyItemType;
+  cursor?: string;
+  maxPassages?: number;
+  maxCharacters?: number;
+  direction?: PaginationDirection;
+}): Promise<PassagesPage> {
+  try {
+    const response = await client.request<GetPassagesResponse>(GET_PASSAGES, {
+      uuid,
+      cursor,
+      limit: maxPassages,
+      direction: mapDirection(direction),
+      filter: type ? { type } : undefined,
+    });
+
+    if (!response.work) {
+      return {
+        passages: [],
+        hasMoreAfter: false,
+        hasMoreBefore: false,
+      };
+    }
+
+    return passagesPageFromGraphQL(response.work.passages, response.work.uuid);
+  } catch (error) {
+    console.error('Error fetching translation passages:', error);
+    return {
+      passages: [],
+      hasMoreAfter: false,
+      hasMoreBefore: false,
+    };
+  }
+}

package/src/lib/functions/get-translation-titles.ts

@@ -0,0 +1,55 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Titles } from '@eightyfourthousand/data-access';
+import { titlesFromGraphQL } from '../mappers';
+
+const GET_WORK_TITLES = gql`
+  query GetWorkWithTitles($uuid: ID!) {
+    work(uuid: $uuid) {
+      titles {
+        uuid
+        content
+        language
+        type
+      }
+    }
+  }
+`;
+
+type GetWorkTitlesResponse = {
+  work: {
+    titles: Array<{
+      uuid: string;
+      content: string;
+      language: string;
+      type: string;
+    }>;
+  } | null;
+};
+
+/**
+ * Get all titles for a work.
+ */
+export async function getTranslationTitles({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<Titles> {
+  try {
+    const response = await client.request<GetWorkTitlesResponse>(
+      GET_WORK_TITLES,
+      { uuid },
+    );
+
+    if (!response.work) {
+      return [];
+    }
+
+    return titlesFromGraphQL(response.work.titles);
+  } catch (error) {
+    console.error('Error fetching translation titles:', error);
+    return [];
+  }
+}

package/src/lib/functions/get-translation-toc.ts

@@ -0,0 +1,115 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Toc } from '@eightyfourthousand/data-access';
+import { tocFromGraphQL } from '../mappers';
+
+const GET_WORK_WITH_TOC = gql`
+  fragment TocEntryFields on TocEntry {
+    uuid
+    content
+    label
+    sort
+    level
+    section
+  }
+
+  fragment TocEntryNested on TocEntry {
+    ...TocEntryFields
+    children {
+      ...TocEntryFields
+      children {
+        ...TocEntryFields
+        children {
+          ...TocEntryFields
+          children {
+            ...TocEntryFields
+            children {
+              ...TocEntryFields
+              children {
+                ...TocEntryFields
+                children {
+                  ...TocEntryFields
+                  children {
+                    ...TocEntryFields
+                    children {
+                      ...TocEntryFields
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  fragment TocFields on Toc {
+    frontMatter {
+      ...TocEntryNested
+    }
+    body {
+      ...TocEntryNested
+    }
+    backMatter {
+      ...TocEntryNested
+    }
+  }
+
+  query GetWorkWithToc($uuid: ID!) {
+    work(uuid: $uuid) {
+      uuid
+      toc {
+        ...TocFields
+      }
+    }
+  }
+`;
+
+type GetWorkWithTocResponse = {
+  work: {
+    uuid: string;
+    toc: {
+      frontMatter: TocEntryNode[];
+      body: TocEntryNode[];
+      backMatter: TocEntryNode[];
+    } | null;
+  } | null;
+};
+
+type TocEntryNode = {
+  uuid: string;
+  content: string;
+  label?: string | null;
+  sort: number;
+  level: number;
+  section: string;
+  children?: TocEntryNode[] | null;
+};
+
+/**
+ * Get the table of contents for a translation work.
+ */
+export async function getTranslationToc({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<Toc | undefined> {
+  try {
+    const response = await client.request<GetWorkWithTocResponse>(
+      GET_WORK_WITH_TOC,
+      { uuid },
+    );
+
+    if (!response.work?.toc) {
+      return undefined;
+    }
+
+    return tocFromGraphQL(response.work.toc);
+  } catch (error) {
+    console.error('Error fetching translation TOC:', error);
+    return undefined;
+  }
+}

package/src/lib/functions/get-translation-uuids.ts

@@ -0,0 +1,63 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+
+const DEFAULT_PAGE_SIZE = 200;
+
+const GET_WORK_UUIDS = gql`
+  query GetWorkUuids($cursor: String, $limit: Int, $filter: WorkFilter) {
+    works(cursor: $cursor, limit: $limit, filter: $filter) {
+      items {
+        uuid
+      }
+      pageInfo {
+        nextCursor
+        hasMoreAfter
+      }
+    }
+  }
+`;
+
+type GetWorkUuidsResponse = {
+  works: {
+    items: Array<{ uuid: string }>;
+    pageInfo: {
+      nextCursor: string | null;
+      hasMoreAfter: boolean;
+    };
+  };
+};
+
+type WorkFilter = {
+  maxPages?: number;
+};
+
+/**
+ * Get work UUIDs with optional filtering.
+ * @param client - GraphQL client
+ * @param filter - Optional filter criteria (e.g., maxPages)
+ * @param limit - Optional limit on total results (fetches all pages if not specified)
+ */
+export async function getTranslationUuids({
+  client,
+  filter,
+  limit,
+}: {
+  client: GraphQLClient;
+  filter?: WorkFilter;
+  limit?: number;
+}): Promise<string[]> {
+  try {
+    // Single request - no pagination needed for static params
+    const response: GetWorkUuidsResponse =
+      await client.request<GetWorkUuidsResponse>(GET_WORK_UUIDS, {
+        cursor: null,
+        limit: limit ?? DEFAULT_PAGE_SIZE,
+        filter,
+      });
+
+    return response.works.items.map((w) => w.uuid);
+  } catch (error) {
+    console.error('Error fetching translation UUIDs:', error);
+    return [];
+  }
+}

package/src/lib/functions/get-translations-metadata.ts

@@ -0,0 +1,81 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Work } from '@eightyfourthousand/data-access';
+import { worksFromGraphQL } from '../mappers';
+
+const GET_ALL_WORKS = gql`
+  query GetAllWorks($cursor: String, $limit: Int) {
+    works(cursor: $cursor, limit: $limit) {
+      items {
+        uuid
+        title
+        toh
+        publicationDate
+        publicationVersion
+        pages
+        restriction
+        section
+      }
+      pageInfo {
+        nextCursor
+        hasMoreAfter
+      }
+    }
+  }
+`;
+
+type GraphQLWork = {
+  uuid: string;
+  title: string;
+  toh: string[];
+  publicationDate: string;
+  publicationVersion: string;
+  pages: number;
+  restriction: boolean;
+  section: string;
+};
+
+type GetAllWorksResponse = {
+  works: {
+    items: GraphQLWork[];
+    pageInfo: {
+      nextCursor: string | null;
+      hasMoreAfter: boolean;
+    };
+  };
+};
+
+/**
+ * Get metadata for all published translation works (fetches all pages).
+ */
+export async function getTranslationsMetadata({
+  client,
+  limit = 200,
+}: {
+  client: GraphQLClient;
+  limit?: number;
+}): Promise<Work[]> {
+  try {
+    const allWorks: GraphQLWork[] = [];
+    let cursor: string | null = null;
+
+    // Fetch all pages
+    do {
+      const response: GetAllWorksResponse =
+        await client.request<GetAllWorksResponse>(GET_ALL_WORKS, {
+          cursor,
+          limit,
+        });
+
+      allWorks.push(...response.works.items);
+      cursor = response.works.pageInfo.hasMoreAfter
+        ? response.works.pageInfo.nextCursor
+        : null;
+    } while (cursor !== null);
+
+    return worksFromGraphQL(allWorks);
+  } catch (error) {
+    console.error('Error fetching translations metadata:', error);
+    return [];
+  }
+}

package/src/lib/functions/get-work-bibliography.ts

@@ -0,0 +1,47 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { BibliographyEntries } from '@eightyfourthousand/data-access';
+
+const GET_WORK_BIBLIOGRAPHY = gql`
+  query GetWorkBibliography($uuid: ID!) {
+    work(uuid: $uuid) {
+      bibliography {
+        heading
+        entries {
+          uuid
+          html
+          workUuid
+        }
+      }
+    }
+  }
+`;
+
+type GetWorkBibliographyResponse = {
+  work: {
+    bibliography: BibliographyEntries;
+  } | null;
+};
+
+/**
+ * Get bibliography entries for a specific work.
+ */
+export async function getWorkBibliography({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<BibliographyEntries> {
+  try {
+    const response = await client.request<GetWorkBibliographyResponse>(
+      GET_WORK_BIBLIOGRAPHY,
+      { uuid },
+    );
+
+    return response.work?.bibliography ?? [];
+  } catch (error) {
+    console.error('Error fetching work bibliography:', error);
+    return [];
+  }
+}

package/src/lib/functions/get-work-folios.ts

@@ -0,0 +1,52 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Folio } from '@eightyfourthousand/data-access';
+
+const GET_WORK_FOLIOS = gql`
+  query GetWorkFolios($uuid: ID!, $toh: String!, $page: Int, $size: Int) {
+    work(uuid: $uuid) {
+      folios(toh: $toh, page: $page, size: $size) {
+        uuid
+        content
+        volume
+        folio
+        side
+      }
+    }
+  }
+`;
+
+type GetWorkFoliosResponse = {
+  work: {
+    folios: Folio[];
+  } | null;
+};
+
+/**
+ * Get folios for a specific work, filtered by toh and paginated.
+ */
+export async function getWorkFolios({
+  client,
+  uuid,
+  toh,
+  page = 0,
+  size = 10,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  toh: string;
+  page?: number;
+  size?: number;
+}): Promise<Folio[]> {
+  try {
+    const response = await client.request<GetWorkFoliosResponse>(
+      GET_WORK_FOLIOS,
+      { uuid, toh, page, size },
+    );
+
+    return response.work?.folios ?? [];
+  } catch (error) {
+    console.error('Error fetching work folios:', error);
+    return [];
+  }
+}

package/src/lib/functions/get-work-glossary-terms-around.ts

@@ -0,0 +1,126 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { GlossaryTermInstance } from '@eightyfourthousand/data-access';
+import type { GlossaryTermsPage } from './get-work-glossary-terms';
+
+const GET_WORK_GLOSSARY_TERMS_AROUND = gql`
+  query GetWorkGlossaryTermsAround(
+    $uuid: ID!
+    $cursor: String!
+    $limit: Int
+    $withAttestations: Boolean
+  ) {
+    work(uuid: $uuid) {
+      glossaryTerms(
+        cursor: $cursor
+        limit: $limit
+        direction: AROUND
+        withAttestations: $withAttestations
+      ) {
+        nodes {
+          uuid
+          authority
+          definition
+          termNumber
+          names {
+            english
+            tibetan
+            sanskrit
+            pali
+            chinese
+            wylie
+          }
+          passages(first: 10) {
+            items {
+              uuid
+              type
+              label
+            }
+            nextCursor
+            hasMore
+          }
+        }
+        pageInfo {
+          nextCursor
+          prevCursor
+          hasMoreAfter
+          hasMoreBefore
+        }
+        totalCount
+      }
+    }
+  }
+`;
+
+type GetWorkGlossaryTermsAroundResponse = {
+  work: {
+    glossaryTerms: {
+      nodes: GlossaryTermInstance[];
+      pageInfo: {
+        nextCursor?: string | null;
+        prevCursor?: string | null;
+        hasMoreAfter: boolean;
+        hasMoreBefore: boolean;
+      };
+      totalCount: number;
+    };
+  } | null;
+};
+
+/**
+ * Get glossary terms around a specific term UUID.
+ * Used for navigating to a glossary entry that hasn't been loaded yet.
+ */
+export async function getWorkGlossaryTermsAround({
+  client,
+  uuid,
+  termUuid,
+  limit,
+  withAttestations = false,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  termUuid: string;
+  limit?: number;
+  withAttestations?: boolean;
+}): Promise<GlossaryTermsPage> {
+  try {
+    const response = await client.request<GetWorkGlossaryTermsAroundResponse>(
+      GET_WORK_GLOSSARY_TERMS_AROUND,
+      {
+        uuid,
+        cursor: termUuid,
+        limit,
+        withAttestations,
+      },
+    );
+
+    if (!response.work) {
+      return {
+        terms: [],
+        hasMoreAfter: false,
+        hasMoreBefore: false,
+        totalCount: 0,
+      };
+    }
+
+    const { glossaryTerms } = response.work;
+
+    return {
+      terms: glossaryTerms.nodes,
+      nextCursor: glossaryTerms.pageInfo.nextCursor ?? undefined,
+      prevCursor: glossaryTerms.pageInfo.prevCursor ?? undefined,
+      hasMoreAfter: glossaryTerms.pageInfo.hasMoreAfter,
+      hasMoreBefore: glossaryTerms.pageInfo.hasMoreBefore,
+      totalCount: glossaryTerms.totalCount,
+    };
+  } catch (error) {
+    console.error('Error fetching glossary terms around:', error);
+    return {
+      terms: [],
+      hasMoreAfter: false,
+      hasMoreBefore: false,
+      totalCount: 0,
+    };
+  }
+}