@eightyfourthousand/client-graphql 2026.3.0

package/src/lib/functions/get-translation-blocks-around.ts

@@ -0,0 +1,131 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { BodyItemType, TranslationEditorContentItem } from '@eightyfourthousand/data-access';
+import type { TranslationBlocksPage } from './get-translation-blocks';
+
+const GET_PASSAGES_AROUND_WITH_JSON = gql`
+  fragment PassageWithJson on Passage {
+    uuid
+    workUuid
+    label
+    sort
+    type
+    xmlId
+    json
+  }
+
+  query GetPassagesAroundWithJson(
+    $uuid: ID!
+    $cursor: String!
+    $limit: Int
+    $filter: PassageFilter
+  ) {
+    work(uuid: $uuid) {
+      uuid
+      passages(
+        cursor: $cursor
+        limit: $limit
+        direction: AROUND
+        filter: $filter
+      ) {
+        nodes {
+          ...PassageWithJson
+        }
+        pageInfo {
+          nextCursor
+          prevCursor
+          hasMoreAfter
+          hasMoreBefore
+        }
+      }
+    }
+  }
+`;
+
+type PassageWithJson = {
+  uuid: string;
+  workUuid: string;
+  label: string;
+  sort: number;
+  type: string;
+  xmlId?: string | null;
+  json?: unknown | null;
+};
+
+type GetPassagesAroundWithJsonResponse = {
+  work: {
+    uuid: string;
+    passages: {
+      nodes: PassageWithJson[];
+      pageInfo: {
+        nextCursor?: string | null;
+        prevCursor?: string | null;
+        hasMoreAfter: boolean;
+        hasMoreBefore: boolean;
+      };
+    };
+  } | null;
+};
+
+/**
+ * Get translation blocks (TipTap JSON) around a specific passage UUID.
+ *
+ * Unlike getTranslationPassagesAround which returns Passage objects,
+ * this function returns pre-transformed TipTap editor blocks
+ * ready for rendering.
+ */
+export async function getTranslationBlocksAround({
+  client,
+  uuid,
+  passageUuid,
+  type,
+  maxPassages,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  passageUuid: string;
+  type?: BodyItemType | string;
+  maxPassages?: number;
+}): Promise<TranslationBlocksPage> {
+  try {
+    const response = await client.request<GetPassagesAroundWithJsonResponse>(
+      GET_PASSAGES_AROUND_WITH_JSON,
+      {
+        uuid,
+        cursor: passageUuid,
+        limit: maxPassages,
+        filter: type ? { type } : undefined,
+      },
+    );
+
+    if (!response.work) {
+      return {
+        blocks: [],
+        hasMoreAfter: false,
+        hasMoreBefore: false,
+      };
+    }
+
+    const { passages } = response.work;
+
+    // Extract the JSON blocks, filtering out any null values
+    const blocks = passages.nodes
+      .map((node) => node.json)
+      .filter((json): json is TranslationEditorContentItem => json != null);
+
+    return {
+      blocks,
+      nextCursor: passages.pageInfo.nextCursor ?? undefined,
+      prevCursor: passages.pageInfo.prevCursor ?? undefined,
+      hasMoreAfter: passages.pageInfo.hasMoreAfter,
+      hasMoreBefore: passages.pageInfo.hasMoreBefore,
+    };
+  } catch (error) {
+    console.error('Error fetching translation blocks around:', error);
+    return {
+      blocks: [],
+      hasMoreAfter: false,
+      hasMoreBefore: false,
+    };
+  }
+}

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

@@ -0,0 +1,160 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type {
+  BodyItemType,
+  PaginationDirection,
+  TranslationEditorContent,
+  TranslationEditorContentItem,
+} from '@eightyfourthousand/data-access';
+
+const GET_PASSAGES_WITH_JSON = gql`
+  fragment PassageWithJson on Passage {
+    uuid
+    workUuid
+    label
+    sort
+    type
+    xmlId
+    json
+  }
+
+  query GetPassagesWithJson(
+    $uuid: ID!
+    $cursor: String
+    $limit: Int
+    $direction: PaginationDirection
+    $filter: PassageFilter
+  ) {
+    work(uuid: $uuid) {
+      uuid
+      passages(
+        cursor: $cursor
+        limit: $limit
+        direction: $direction
+        filter: $filter
+      ) {
+        nodes {
+          ...PassageWithJson
+        }
+        pageInfo {
+          nextCursor
+          prevCursor
+          hasMoreAfter
+          hasMoreBefore
+        }
+      }
+    }
+  }
+`;
+
+type PassageWithJson = {
+  uuid: string;
+  workUuid: string;
+  label: string;
+  sort: number;
+  type: string;
+  xmlId?: string | null;
+  json?: unknown | null;
+};
+
+type GetPassagesWithJsonResponse = {
+  work: {
+    uuid: string;
+    passages: {
+      nodes: PassageWithJson[];
+      pageInfo: {
+        nextCursor?: string | null;
+        prevCursor?: string | null;
+        hasMoreAfter: boolean;
+        hasMoreBefore: boolean;
+      };
+    };
+  } | null;
+};
+
+/**
+ * Result of fetching translation blocks with pagination info
+ */
+export type TranslationBlocksPage = {
+  blocks: TranslationEditorContent;
+  nextCursor?: string;
+  prevCursor?: string;
+  hasMoreAfter: boolean;
+  hasMoreBefore: boolean;
+};
+
+/**
+ * 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 translation blocks (TipTap JSON) for a work.
+ *
+ * Unlike getTranslationPassages which returns Passage objects,
+ * this function returns pre-transformed TipTap editor blocks
+ * ready for rendering.
+ */
+export async function getTranslationBlocks({
+  client,
+  uuid,
+  type,
+  cursor,
+  maxPassages = 100,
+  direction,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  type?: BodyItemType | string;
+  cursor?: string;
+  maxPassages?: number;
+  direction?: PaginationDirection;
+}): Promise<TranslationBlocksPage> {
+  try {
+    const response = await client.request<GetPassagesWithJsonResponse>(
+      GET_PASSAGES_WITH_JSON,
+      {
+        uuid,
+        cursor,
+        limit: maxPassages,
+        direction: mapDirection(direction),
+        filter: type ? { type } : undefined,
+      },
+    );
+
+    if (!response.work) {
+      return {
+        blocks: [],
+        hasMoreAfter: false,
+        hasMoreBefore: false,
+      };
+    }
+
+    const { passages } = response.work;
+
+    // Extract the JSON blocks, filtering out any null values
+    const blocks = passages.nodes
+      .map((node) => node.json)
+      .filter((json): json is TranslationEditorContentItem => json != null);
+
+    return {
+      blocks,
+      nextCursor: passages.pageInfo.nextCursor ?? undefined,
+      prevCursor: passages.pageInfo.prevCursor ?? undefined,
+      hasMoreAfter: passages.pageInfo.hasMoreAfter,
+      hasMoreBefore: passages.pageInfo.hasMoreBefore,
+    };
+  } catch (error) {
+    console.error('Error fetching translation blocks:', error);
+    return {
+      blocks: [],
+      hasMoreAfter: false,
+      hasMoreBefore: false,
+    };
+  }
+}

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

@@ -0,0 +1,114 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Imprint } from '@eightyfourthousand/data-access';
+import { imprintFromGraphQL } from '../mappers';
+
+const GET_WORK_WITH_IMPRINT = gql`
+  fragment LicenseFields on License {
+    name
+    link
+    description
+  }
+
+  fragment TitlesByLanguageFields on TitlesByLanguage {
+    tibetan
+    english
+    wylie
+    sanskrit
+  }
+
+  fragment ImprintFields on Imprint {
+    toh
+    section
+    version
+    restriction
+    publishYear
+    tibetanAuthors
+    isAuthorContested
+    sourceDescription
+    publisherStatement
+    tibetanTranslators
+    license {
+      ...LicenseFields
+    }
+    mainTitles {
+      ...TitlesByLanguageFields
+    }
+    longTitles {
+      ...TitlesByLanguageFields
+    }
+  }
+
+  query GetWorkWithImprint($uuid: ID!, $toh: String) {
+    work(uuid: $uuid, toh: $toh) {
+      uuid
+      imprint {
+        ...ImprintFields
+      }
+    }
+  }
+`;
+
+type GetWorkWithImprintResponse = {
+  work: {
+    uuid: string;
+    imprint: {
+      toh: string;
+      section?: string | null;
+      version?: string | null;
+      restriction?: boolean | null;
+      publishYear?: string | null;
+      tibetanAuthors?: string[] | null;
+      isAuthorContested: boolean;
+      sourceDescription?: string | null;
+      publisherStatement?: string | null;
+      tibetanTranslators?: string | null;
+      license: {
+        name?: string | null;
+        link?: string | null;
+        description?: string | null;
+      } | null;
+      mainTitles?: {
+        tibetan?: string | null;
+        english?: string | null;
+        wylie?: string | null;
+        sanskrit?: string | null;
+      } | null;
+      longTitles?: {
+        tibetan?: string | null;
+        english?: string | null;
+        wylie?: string | null;
+        sanskrit?: string | null;
+      } | null;
+    } | null;
+  } | null;
+};
+
+/**
+ * Get the imprint for a translation work.
+ */
+export async function getTranslationImprint({
+  client,
+  uuid,
+  toh,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  toh: string;
+}): Promise<Imprint | undefined> {
+  try {
+    const response = await client.request<GetWorkWithImprintResponse>(
+      GET_WORK_WITH_IMPRINT,
+      { uuid, toh },
+    );
+
+    if (!response.work?.imprint) {
+      return undefined;
+    }
+
+    return imprintFromGraphQL(response.work.imprint, response.work.uuid);
+  } catch (error) {
+    console.error('Error fetching translation imprint:', error);
+    return undefined;
+  }
+}

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

@@ -0,0 +1,99 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Work } from '@eightyfourthousand/data-access';
+import { workFromGraphQL } from '../mappers';
+
+const GET_WORK_BY_UUID = gql`
+  query GetWorkByUuid($uuid: ID!) {
+    work(uuid: $uuid) {
+      uuid
+      title
+      toh
+      publicationDate
+      publicationVersion
+      pages
+      restriction
+      section
+    }
+  }
+`;
+
+const GET_WORK_BY_TOH = gql`
+  query GetWorkByToh($toh: String!) {
+    work(toh: $toh) {
+      uuid
+      title
+      toh
+      publicationDate
+      publicationVersion
+      pages
+      restriction
+      section
+    }
+  }
+`;
+
+type GetWorkResponse = {
+  work: {
+    uuid: string;
+    title: string;
+    toh: string[];
+    publicationDate: string;
+    publicationVersion: string;
+    pages: number;
+    restriction: boolean;
+    section: string;
+  } | null;
+};
+
+/**
+ * Get work metadata by UUID.
+ */
+export async function getTranslationMetadataByUuid({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<Work | null> {
+  try {
+    const response = await client.request<GetWorkResponse>(GET_WORK_BY_UUID, {
+      uuid,
+    });
+
+    if (!response.work) {
+      return null;
+    }
+
+    return workFromGraphQL(response.work);
+  } catch (error) {
+    console.error('Error fetching translation metadata by UUID:', error);
+    return null;
+  }
+}
+
+/**
+ * Get work metadata by Tohoku catalog number.
+ */
+export async function getTranslationMetadataByToh({
+  client,
+  toh,
+}: {
+  client: GraphQLClient;
+  toh: string;
+}): Promise<Work | null> {
+  try {
+    const response = await client.request<GetWorkResponse>(GET_WORK_BY_TOH, {
+      toh,
+    });
+
+    if (!response.work) {
+      return null;
+    }
+
+    return workFromGraphQL(response.work);
+  } catch (error) {
+    console.error('Error fetching translation metadata by toh:', error);
+    return null;
+  }
+}

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

@@ -0,0 +1,153 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { BodyItemType, PassagesPage } from '@eightyfourthousand/data-access';
+import { passagesPageFromGraphQL } from '../mappers';
+
+const GET_PASSAGES_AROUND = 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 GetPassagesAround(
+    $uuid: ID!
+    $cursor: String!
+    $limit: Int
+    $filter: PassageFilter
+  ) {
+    work(uuid: $uuid) {
+      uuid
+      passages(
+        cursor: $cursor
+        limit: $limit
+        direction: AROUND
+        filter: $filter
+      ) {
+        nodes {
+          ...PassageWithAnnotations
+        }
+        pageInfo {
+          nextCursor
+          prevCursor
+          hasMoreAfter
+          hasMoreBefore
+        }
+      }
+    }
+  }
+`;
+
+type GetPassagesAroundResponse = {
+  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;
+};
+
+/**
+ * Get passages around a specific passage UUID.
+ *
+ * NOTE: maxCharacters is not supported by the GraphQL API yet.
+ * This parameter is accepted for API compatibility but is ignored.
+ */
+export async function getTranslationPassagesAround({
+  client,
+  uuid,
+  passageUuid,
+  type,
+  maxPassages,
+  maxCharacters: _maxCharacters,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  passageUuid: string;
+  type?: BodyItemType;
+  maxPassages?: number;
+  maxCharacters?: number;
+}): Promise<PassagesPage> {
+  try {
+    const response = await client.request<GetPassagesAroundResponse>(
+      GET_PASSAGES_AROUND,
+      {
+        uuid,
+        cursor: passageUuid,
+        limit: maxPassages,
+        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 around:', error);
+    return {
+      passages: [],
+      hasMoreAfter: false,
+      hasMoreBefore: false,
+    };
+  }
+}