@eightyfourthousand/client-graphql 2026.3.0

package/codegen.ts

@@ -0,0 +1,34 @@
+import type { CodegenConfig } from '@graphql-codegen/cli';
+import { join } from 'path';
+
+// Resolve paths from repo root
+const repoRoot = join(__dirname, '../..');
+const schemaPath = join(repoRoot, 'apps/api-graphql/src/graphql/schema/**/*.graphql');
+const documentsPath = join(__dirname, 'src/lib/graphql/**/*.graphql');
+const outputPath = join(__dirname, 'src/lib/generated/graphql.ts');
+
+const config: CodegenConfig = {
+  schema: schemaPath,
+  documents: documentsPath,
+  generates: {
+    [outputPath]: {
+      plugins: [
+        'typescript',
+        'typescript-operations',
+        'typescript-graphql-request',
+      ],
+      config: {
+        rawRequest: false,
+        inlineFragmentTypes: 'combine',
+        skipTypename: false,
+        exportFragmentSpreadSubTypes: true,
+        dedupeFragments: true,
+        enumsAsTypes: true,
+        useTypeImports: true,
+      },
+    },
+  },
+  ignoreNoDocuments: false,
+};
+
+export default config;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@eightyfourthousand/client-graphql",
+  "version": "2026.3.0",
+  "description": "GraphQL client helpers and typed query functions for 84000 applications.",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/84000/84000-apps.git",
+    "directory": "libs/client-graphql"
+  },
+  "homepage": "https://github.com/84000/84000-apps",
+  "bugs": {
+    "url": "https://github.com/84000/84000-apps/issues"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@eightyfourthousand/data-access": "^2026.3.0"
+  },
+  "sideEffects": false,
+  "keywords": [],
+  "author": ""
+}

package/project.json

@@ -0,0 +1,21 @@
+{
+  "name": "client-graphql",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/client-graphql/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/client-graphql",
+        "main": "libs/client-graphql/src/index.ts",
+        "tsConfig": "libs/client-graphql/tsconfig.lib.json",
+        "rootDir": "libs/client-graphql/src",
+        "generateExportsField": true,
+        "additionalEntryPoints": ["libs/client-graphql/src/ssr.ts"]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+// Client
+export {
+  createGraphQLClient,
+  resetGraphQLClient,
+  setAccessTokenProvider,
+} from './lib/client';
+
+// Functions
+export {
+  getPassage,
+  getTranslationPassages,
+  getTranslationPassagesAround,
+  getTranslationBlocks,
+  getTranslationBlocksAround,
+  getTranslationTitles,
+  getTranslationMetadataByUuid,
+  getTranslationMetadataByToh,
+  getTranslationsMetadata,
+  getTranslationUuids,
+  getTranslationToc,
+  getTranslationImprint,
+  getGlossaryTerms,
+  getGlossaryEntry,
+  getGlossaryInstance,
+  getWorkGlossary,
+  getWorkGlossaryTerms,
+  getWorkGlossaryTermsAround,
+  type GlossaryTermsPage,
+  getTermPassages,
+  type GlossaryPassagesPage,
+  getBibliographyEntry,
+  getWorkBibliography,
+  getWorkFolios,
+  getWorks,
+  hasPermission,
+  savePassages,
+  type TranslationBlocksPage,
+  type WorksPage,
+  type Permission,
+} from './lib/functions';
+
+// Re-export types from @eightyfourthousand/data-access for convenience
+export type {
+  Passage,
+  Passages,
+  PassagesPage,
+  PaginationDirection,
+  BodyItemType,
+  Annotation,
+  Annotations,
+  Alignment,
+  Work,
+  Title,
+  Titles,
+  TitleType,
+  Toc,
+  TocEntry,
+  Imprint,
+  GlossaryTermInstance,
+  GlossaryLandingItem,
+  GlossaryPageItem,
+  BibliographyEntry,
+  BibliographyEntryItem,
+  BibliographyEntries,
+  Folio,
+} from '@eightyfourthousand/data-access';
+
+// Re-export constants for passage filters
+export {
+  BODY_ITEM_TYPES,
+  FRONT_MATTER,
+  FRONT_MATTER_FILTER,
+  BODY_MATTER,
+  BODY_MATTER_FILTER,
+  BACK_MATTER,
+  BACK_MATTER_FILTER,
+  COMPARE_MODE,
+  COMPARE_MODE_FILTER,
+} from '@eightyfourthousand/data-access';

package/src/lib/client-ssr.ts

@@ -0,0 +1,44 @@
+import 'server-only';
+import { GraphQLClient } from 'graphql-request';
+import { cookies } from 'next/headers';
+import { getGraphQLUrl } from './config';
+
+/**
+ * Create a GraphQL client for server-side requests (SSR/RSC).
+ * Reads auth cookies from the request and forwards them to the GraphQL API.
+ *
+ * Must be called within a Server Component or Server Action context.
+ */
+export async function createServerGraphQLClient(): Promise<GraphQLClient> {
+  const url = getGraphQLUrl();
+
+  // Get all cookies from the request
+  const cookieStore = await cookies();
+  const allCookies = cookieStore.getAll();
+
+  // Build cookie header string with encoded values to ensure HTTP header compatibility
+  // Cookie values may contain non-ASCII characters which are invalid in HTTP headers (ByteString)
+  const cookieHeader = allCookies
+    .map((cookie) => `${cookie.name}=${encodeURIComponent(cookie.value)}`)
+    .join('; ');
+
+  const client = new GraphQLClient(url, {
+    headers: {
+      // Forward cookies for authentication
+      ...(cookieHeader ? { cookie: cookieHeader } : {}),
+    },
+  });
+
+  return client;
+}
+
+/**
+ * Create a GraphQL client for build-time requests (generateStaticParams).
+ * Does not use cookies since there's no request context during builds.
+ *
+ * Use this in generateStaticParams and other build-time contexts.
+ */
+export function createBuildGraphQLClient(): GraphQLClient {
+  const url = getGraphQLUrl();
+  return new GraphQLClient(url);
+}

package/src/lib/client.ts

@@ -0,0 +1,58 @@
+import { GraphQLClient } from 'graphql-request';
+import { getGraphQLUrl } from './config';
+
+let clientInstance: GraphQLClient | null = null;
+let getAccessToken: (() => Promise<string | null>) | null = null;
+
+/**
+ * Set the access token provider function.
+ * This should be called once at app initialization.
+ */
+export function setAccessTokenProvider(
+  provider: () => Promise<string | null>
+): void {
+  getAccessToken = provider;
+}
+
+/**
+ * Create a GraphQL client for browser-side requests.
+ * Uses Authorization header with dynamic token retrieval for cross-domain requests.
+ */
+export function createGraphQLClient(): GraphQLClient {
+  if (clientInstance) {
+    return clientInstance;
+  }
+
+  const url = getGraphQLUrl();
+
+  clientInstance = new GraphQLClient(url, {
+    // Dynamic headers - called on each request
+    requestMiddleware: async (request) => {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'apollo-require-preflight': 'true',
+      };
+
+      if (getAccessToken) {
+        const token = await getAccessToken();
+        if (token) {
+          headers['Authorization'] = `Bearer ${token}`;
+        }
+      }
+
+      return {
+        ...request,
+        headers,
+      };
+    },
+  });
+
+  return clientInstance;
+}
+
+/**
+ * Reset the client instance (useful for testing)
+ */
+export function resetGraphQLClient(): void {
+  clientInstance = null;
+}

package/src/lib/config.ts

@@ -0,0 +1,21 @@
+/**
+ * GraphQL API configuration
+ */
+
+/**
+ * Get the GraphQL API URL from environment variables
+ * Falls back to localhost for development
+ */
+export function getGraphQLUrl(): string {
+  const url = process.env.NEXT_PUBLIC_GRAPHQL_URL;
+
+  if (!url) {
+    // Default to localhost in development
+    if (process.env.NODE_ENV === 'development') {
+      return 'http://localhost:3001/api/graphql';
+    }
+    throw new Error('NEXT_PUBLIC_GRAPHQL_URL environment variable is not set');
+  }
+
+  return url;
+}

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

@@ -0,0 +1,40 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { BibliographyEntryItem } from '@eightyfourthousand/data-access';
+
+const GET_BIBLIOGRAPHY_ENTRY = gql`
+  query GetBibliographyEntry($uuid: ID!) {
+    bibliographyEntry(uuid: $uuid) {
+      uuid
+      html
+      workUuid
+    }
+  }
+`;
+
+type GetBibliographyEntryResponse = {
+  bibliographyEntry: BibliographyEntryItem | null;
+};
+
+/**
+ * Get a single bibliography entry by UUID.
+ */
+export async function getBibliographyEntry({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<BibliographyEntryItem | null> {
+  try {
+    const response = await client.request<GetBibliographyEntryResponse>(
+      GET_BIBLIOGRAPHY_ENTRY,
+      { uuid },
+    );
+
+    return response.bibliographyEntry;
+  } catch (error) {
+    console.error('Error fetching bibliography entry:', error);
+    return null;
+  }
+}

package/src/lib/functions/get-glossary-entry.ts

@@ -0,0 +1,136 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { GlossaryPageItem, TohokuCatalogEntry } from '@eightyfourthousand/data-access';
+
+const GET_GLOSSARY_ENTRY = gql`
+  query GetGlossaryEntry($uuid: ID!) {
+    glossaryEntry(uuid: $uuid) {
+      authorityUuid
+      headword
+      language
+      classifications
+      definition
+      xmlId
+      english
+      tibetan
+      sanskrit
+      pali
+      chinese
+      relatedInstances {
+        workUuid
+        toh
+        definition
+        canon
+        english
+        tibetan
+        sanskrit
+        pali
+        chinese
+        creators
+      }
+      relatedEntities {
+        sourceHeadword
+        sourceUuid
+        targetHeadword
+        targetUuid
+      }
+    }
+  }
+`;
+
+type GraphQLGlossaryEntry = {
+  authorityUuid: string;
+  headword: string;
+  language: string;
+  classifications: string[];
+  definition: string | null;
+  xmlId: string | null;
+  english: string[];
+  tibetan: string[];
+  sanskrit: string[];
+  pali: string[];
+  chinese: string[];
+  relatedInstances: Array<{
+    workUuid: string;
+    toh: string;
+    definition: string | null;
+    canon: string | null;
+    english: string[];
+    tibetan: string[];
+    sanskrit: string[];
+    pali: string[];
+    chinese: string[];
+    creators: string[];
+  }>;
+  relatedEntities: Array<{
+    sourceHeadword: string;
+    sourceUuid: string;
+    targetHeadword: string;
+    targetUuid: string;
+  }>;
+};
+
+type GetGlossaryEntryResponse = {
+  glossaryEntry: GraphQLGlossaryEntry | null;
+};
+
+/**
+ * Map GraphQL glossary entry to the GlossaryPageItem type.
+ */
+function glossaryEntryFromGraphQL(
+  entry: GraphQLGlossaryEntry,
+): GlossaryPageItem {
+  return {
+    authorityUuid: entry.authorityUuid,
+    headword: entry.headword,
+    language: entry.language as GlossaryPageItem['language'],
+    classifications: entry.classifications,
+    definition: entry.definition ?? undefined,
+    xmlId: entry.xmlId ?? undefined,
+    english: entry.english,
+    tibetan: entry.tibetan,
+    sanskrit: entry.sanskrit,
+    pali: entry.pali,
+    chinese: entry.chinese,
+    relatedInstances: entry.relatedInstances.map((instance) => ({
+      workUuid: instance.workUuid,
+      toh: instance.toh as TohokuCatalogEntry,
+      definition: instance.definition ?? undefined,
+      canon: instance.canon ?? undefined,
+      english: instance.english,
+      tibetan: instance.tibetan,
+      sanskrit: instance.sanskrit,
+      pali: instance.pali,
+      chinese: instance.chinese,
+      creators: instance.creators,
+    })),
+    relatedEntities: entry.relatedEntities,
+  };
+}
+
+/**
+ * Get a single glossary entry by UUID (for the detail page).
+ */
+export async function getGlossaryEntry({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<GlossaryPageItem | null> {
+  try {
+    const response = await client.request<GetGlossaryEntryResponse>(
+      GET_GLOSSARY_ENTRY,
+      { uuid },
+    );
+
+    if (!response.glossaryEntry) {
+      return null;
+    }
+
+    return glossaryEntryFromGraphQL(response.glossaryEntry);
+  } catch (error) {
+    console.error('Error fetching glossary entry:', error);
+    return null;
+  }
+}

package/src/lib/functions/get-glossary-instance.ts

@@ -0,0 +1,48 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { GlossaryTermInstance } from '@eightyfourthousand/data-access';
+
+const GET_GLOSSARY_INSTANCE = gql`
+  query GetGlossaryInstance($uuid: ID!) {
+    glossaryInstance(uuid: $uuid) {
+      uuid
+      authority
+      definition
+      names {
+        english
+        tibetan
+        sanskrit
+        pali
+        chinese
+        wylie
+      }
+    }
+  }
+`;
+
+type GetGlossaryInstanceResponse = {
+  glossaryInstance: GlossaryTermInstance | null;
+};
+
+/**
+ * Get a single glossary instance by UUID.
+ */
+export async function getGlossaryInstance({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<GlossaryTermInstance | null> {
+  try {
+    const response = await client.request<GetGlossaryInstanceResponse>(
+      GET_GLOSSARY_INSTANCE,
+      { uuid },
+    );
+
+    return response.glossaryInstance;
+  } catch (error) {
+    console.error('Error fetching glossary instance:', error);
+    return null;
+  }
+}

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

@@ -0,0 +1,44 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { GlossaryLandingItem } from '@eightyfourthousand/data-access';
+
+const GET_GLOSSARY_TERMS = gql`
+  query GetGlossaryTerms($uuids: [ID!]) {
+    glossaryTerms(uuids: $uuids) {
+      uuid
+      headword
+      type
+      language
+      nameVariants
+      definition
+      numGlossaryEntries
+    }
+  }
+`;
+
+type GetGlossaryTermsResponse = {
+  glossaryTerms: GlossaryLandingItem[];
+};
+
+/**
+ * Get all glossary terms for the landing page, optionally filtered by UUIDs.
+ */
+export async function getGlossaryTerms({
+  client,
+  uuids,
+}: {
+  client: GraphQLClient;
+  uuids?: string[];
+}): Promise<GlossaryLandingItem[]> {
+  try {
+    const response = await client.request<GetGlossaryTermsResponse>(
+      GET_GLOSSARY_TERMS,
+      { uuids },
+    );
+
+    return response.glossaryTerms;
+  } catch (error) {
+    console.error('Error fetching glossary terms:', error);
+    return [];
+  }
+}

package/src/lib/functions/get-passage.ts

@@ -0,0 +1,78 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+import type { Passage } from '@eightyfourthousand/data-access';
+import { passageFromGraphQL, type GraphQLPassage } from '../mappers';
+
+const GET_PASSAGE = gql`
+  fragment AnnotationFields on Annotation {
+    uuid
+    type
+    start
+    end
+    metadata
+  }
+
+  fragment AlignmentFields on Alignment {
+    folioUuid
+    toh
+    tibetan
+    folioNumber
+    volumeNumber
+  }
+
+  fragment PassageFields on Passage {
+    uuid
+    workUuid
+    content
+    label
+    sort
+    type
+    xmlId
+  }
+
+  fragment PassageWithAnnotations on Passage {
+    ...PassageFields
+    annotations {
+      ...AnnotationFields
+    }
+    alignments {
+      ...AlignmentFields
+    }
+  }
+
+  query GetPassage($uuid: ID!) {
+    passage(uuid: $uuid) {
+      ...PassageWithAnnotations
+    }
+  }
+`;
+
+type GetPassageResponse = {
+  passage: GraphQLPassage | null;
+};
+
+/**
+ * Get a single passage by UUID.
+ */
+export async function getPassage({
+  client,
+  uuid,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+}): Promise<Passage | undefined> {
+  try {
+    const response = await client.request<GetPassageResponse>(GET_PASSAGE, {
+      uuid,
+    });
+
+    if (!response.passage) {
+      return undefined;
+    }
+
+    return passageFromGraphQL(response.passage);
+  } catch (error) {
+    console.error('Error fetching passage:', error);
+    return undefined;
+  }
+}

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

@@ -0,0 +1,53 @@
+import type { GraphQLClient } from 'graphql-request';
+import { gql } from 'graphql-request';
+
+const GET_TERM_PASSAGES = gql`
+  query GetTermPassages($uuid: ID!, $first: Int, $after: String) {
+    glossaryTermPassages(uuid: $uuid, first: $first, after: $after) {
+      items {
+        uuid
+        type
+        label
+        sort
+      }
+      nextCursor
+      hasMore
+    }
+  }
+`;
+
+export type GlossaryPassagesPage = {
+  items: Array<{ uuid: string; type: string; label: string; sort: number }>;
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+
+type GetTermPassagesResponse = {
+  glossaryTermPassages: GlossaryPassagesPage;
+};
+
+/**
+ * Fetch a page of passage references for a single glossary term instance.
+ */
+export async function getTermPassages({
+  client,
+  uuid,
+  first = 10,
+  after,
+}: {
+  client: GraphQLClient;
+  uuid: string;
+  first?: number;
+  after?: string;
+}): Promise<GlossaryPassagesPage> {
+  try {
+    const response = await client.request<GetTermPassagesResponse>(
+      GET_TERM_PASSAGES,
+      { uuid, first, after },
+    );
+    return response.glossaryTermPassages;
+  } catch (error) {
+    console.error('Error fetching term passages:', error);
+    return { items: [], nextCursor: null, hasMore: false };
+  }
+}