@robosystems/client 0.3.0 → 0.3.2

package/{extensions → artifacts}/LedgerClient.ts

@@ -25,38 +25,90 @@
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core'
 import { ClientError } from 'graphql-request'
 import {
+  opAddPublishListMembers,
   opAutoMapElements,
+  opBuildFactGrid,
   opClosePeriod,
+  opCreateAssociations,
   opCreateClosingEntry,
+  opCreateElement,
+  opCreateJournalEntry,
   opCreateManualClosingEntry,
   opCreateMappingAssociation,
+  opCreatePublishList,
+  opCreateReport,
   opCreateSchedule,
   opCreateStructure,
   opCreateTaxonomy,
+  opDeleteAssociation,
+  opDeleteElement,
+  opDeleteJournalEntry,
   opDeleteMappingAssociation,
+  opDeletePublishList,
+  opDeleteReport,
+  opDeleteSchedule,
+  opDeleteStructure,
+  opDeleteTaxonomy,
   opInitializeLedger,
+  opLinkEntityTaxonomy,
+  opRegenerateReport,
+  opRemovePublishListMember,
   opReopenPeriod,
+  opReverseJournalEntry,
   opSetCloseTarget,
+  opShareReport,
   opTruncateSchedule,
+  opUpdateAssociation,
+  opUpdateElement,
   opUpdateEntity,
+  opUpdateJournalEntry,
+  opUpdatePublishList,
+  opUpdateSchedule,
+  opUpdateStructure,
+  opUpdateTaxonomy,
 } from '../sdk.gen'
 import type {
+  AddPublishListMembersOperation,
   AutoMapElementsOperation,
+  BulkAssociationItem,
+  BulkCreateAssociationsRequest,
   ClosePeriodOperation,
   CreateClosingEntryOperation,
+  CreateElementRequest,
+  CreateJournalEntryRequest,
   CreateManualClosingEntryRequest,
   CreateMappingAssociationOperation,
+  CreatePublishListRequest,
+  CreateReportRequest,
   CreateScheduleRequest,
   CreateStructureRequest,
   CreateTaxonomyRequest,
+  CreateViewRequest,
+  DeleteAssociationRequest,
+  DeleteElementRequest,
+  DeleteJournalEntryRequest,
   DeleteMappingAssociationOperation,
+  DeleteScheduleRequest,
+  DeleteStructureRequest,
+  DeleteTaxonomyRequest,
   InitializeLedgerRequest,
+  JournalEntryLineItemInput,
+  LinkEntityTaxonomyRequest,
   OperationEnvelope,
   ReopenPeriodOperation,
+  ReverseJournalEntryRequest,
   SetCloseTargetOperation,
   TruncateScheduleOperation,
+  UpdateAssociationRequest,
+  UpdateElementRequest,
   UpdateEntityRequest,
+  UpdateJournalEntryRequest,
+  UpdatePublishListOperation,
+  UpdateScheduleRequest,
+  UpdateStructureRequest,
+  UpdateTaxonomyRequest,
 } from '../types.gen'
+import type { TokenProvider } from './graphql/client'
 import { GraphQLClientCache } from './graphql/client'
 import {
   GetLedgerAccountRollupsDocument,
@@ -69,8 +121,11 @@ import {
   GetLedgerMappingDocument,
   GetLedgerPeriodCloseStatusDocument,
   GetLedgerPeriodDraftsDocument,
+  GetLedgerPublishListDocument,
+  GetLedgerReportDocument,
   GetLedgerReportingTaxonomyDocument,
   GetLedgerScheduleFactsDocument,
+  GetLedgerStatementDocument,
   GetLedgerSummaryDocument,
   GetLedgerTransactionDocument,
   GetLedgerTrialBalanceDocument,
@@ -78,6 +133,8 @@ import {
   ListLedgerElementsDocument,
   ListLedgerEntitiesDocument,
   ListLedgerMappingsDocument,
+  ListLedgerPublishListsDocument,
+  ListLedgerReportsDocument,
   ListLedgerSchedulesDocument,
   ListLedgerStructuresDocument,
   ListLedgerTaxonomiesDocument,
@@ -93,8 +150,11 @@ import {
   type GetLedgerMappingQuery,
   type GetLedgerPeriodCloseStatusQuery,
   type GetLedgerPeriodDraftsQuery,
+  type GetLedgerPublishListQuery,
   type GetLedgerReportingTaxonomyQuery,
+  type GetLedgerReportQuery,
   type GetLedgerScheduleFactsQuery,
+  type GetLedgerStatementQuery,
   type GetLedgerSummaryQuery,
   type GetLedgerTransactionQuery,
   type GetLedgerTrialBalanceQuery,
@@ -102,6 +162,8 @@ import {
   type ListLedgerElementsQuery,
   type ListLedgerEntitiesQuery,
   type ListLedgerMappingsQuery,
+  type ListLedgerPublishListsQuery,
+  type ListLedgerReportsQuery,
   type ListLedgerSchedulesQuery,
   type ListLedgerStructuresQuery,
   type ListLedgerTaxonomiesQuery,
@@ -173,6 +235,42 @@ export type LedgerClosingBookStructures = NonNullable<
 export type LedgerFiscalCalendar = NonNullable<GetLedgerFiscalCalendarQuery['fiscalCalendar']>
 export type LedgerFiscalPeriod = LedgerFiscalCalendar['periods'][number]
 
+// Reports + publish lists + statements
+export type Report = NonNullable<GetLedgerReportQuery['report']>
+export type ReportListItem = NonNullable<ListLedgerReportsQuery['reports']>['reports'][number]
+export type StatementData = NonNullable<GetLedgerStatementQuery['statement']>
+export type StatementPeriod = StatementData['periods'][number]
+export type StatementRow = StatementData['rows'][number]
+
+export type PublishList = NonNullable<
+  ListLedgerPublishListsQuery['publishLists']
+>['publishLists'][number]
+export type PublishListDetail = NonNullable<GetLedgerPublishListQuery['publishList']>
+export type PublishListMember = PublishListDetail['members'][number]
+
+export interface PeriodSpecInput {
+  start: string
+  end: string
+  label: string
+}
+
+export interface CreateReportOptions {
+  name: string
+  mappingId: string
+  periodStart: string
+  periodEnd: string
+  taxonomyId?: string
+  periodType?: string
+  comparative?: boolean
+  periods?: PeriodSpecInput[]
+}
+
+export interface ReportOperationAck {
+  operationId: string
+  status: OperationEnvelope['status']
+  result: Record<string, unknown> | null
+}
+
 // ── Write result shapes (envelope.result payloads) ─────────────────────
 //
 // Backend Pydantic models serialize these write results in snake_case.
@@ -341,13 +439,36 @@ export interface CreateScheduleOptions {
   }
 }
 
+export interface JournalEntryLineItem {
+  elementId: string
+  debitAmount?: number
+  creditAmount?: number
+  description?: string | null
+}
+
+export interface CreateJournalEntryOptions {
+  postingDate: string
+  memo: string
+  lineItems: JournalEntryLineItem[]
+  type?: LedgerEntryType
+  status?: 'draft' | 'posted'
+  transactionId?: string | null
+  idempotencyKey?: string | null
+}
+
 // ── Client ──────────────────────────────────────────────────────────────
 
 interface LedgerClientConfig {
   baseUrl: string
   credentials?: 'include' | 'same-origin' | 'omit'
   headers?: Record<string, string>
+  /** Static credential — use `tokenProvider` instead if the JWT rotates. */
   token?: string
+  /**
+   * Dynamic credential callback. When set, invoked on every GraphQL
+   * request so refreshes flow through automatically.
+   */
+  tokenProvider?: TokenProvider
 }
 
 export class LedgerClient {
@@ -595,6 +716,43 @@ export class LedgerClient {
     return (envelope.result ?? {}) as Record<string, unknown>
   }
 
+  /** Update mutable fields on a taxonomy. `taxonomy_type` is immutable. */
+  async updateTaxonomy(
+    graphId: string,
+    body: UpdateTaxonomyRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update taxonomy',
+      opUpdateTaxonomy({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Soft-delete a taxonomy (`is_active=false`). */
+  async deleteTaxonomy(graphId: string, taxonomyId: string): Promise<Record<string, unknown>> {
+    const body: DeleteTaxonomyRequest = { taxonomy_id: taxonomyId }
+    const envelope = await this.callOperation(
+      'Delete taxonomy',
+      opDeleteTaxonomy({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /**
+   * Link the graph's entity to a taxonomy (ENTITY_HAS_TAXONOMY edge).
+   * Idempotent — returns existing linkage if already present.
+   */
+  async linkEntityTaxonomy(
+    graphId: string,
+    body: LinkEntityTaxonomyRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Link entity taxonomy',
+      opLinkEntityTaxonomy({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
   /** List elements (CoA accounts, GAAP concepts, etc.) with filters. */
   async listElements(
     graphId: string,
@@ -637,6 +795,40 @@ export class LedgerClient {
     )
   }
 
+  /** Create a new element within a taxonomy (native CoA account, etc.). */
+  async createElement(
+    graphId: string,
+    body: CreateElementRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Create element',
+      opCreateElement({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Update mutable fields on an element. `taxonomy_id` and `source` are immutable. */
+  async updateElement(
+    graphId: string,
+    body: UpdateElementRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update element',
+      opUpdateElement({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Soft-delete an element (`is_active=false`). */
+  async deleteElement(graphId: string, elementId: string): Promise<Record<string, unknown>> {
+    const body: DeleteElementRequest = { element_id: elementId }
+    const envelope = await this.callOperation(
+      'Delete element',
+      opDeleteElement({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
   // ── Structures ──────────────────────────────────────────────────────
 
   /** List reporting structures (IS, BS, CF, schedules) with optional filters. */
@@ -669,6 +861,50 @@ export class LedgerClient {
     return envelope.result as unknown as LedgerMappingInfo
   }
 
+  /** Convenience wrapper — create a CoA→GAAP mapping structure. */
+  async createMappingStructure(
+    graphId: string,
+    options?: {
+      name?: string
+      description?: string | null
+      taxonomyId?: string
+    }
+  ): Promise<LedgerMappingInfo> {
+    const body: CreateStructureRequest = {
+      name: options?.name ?? 'CoA to Reporting',
+      structure_type: 'coa_mapping',
+      taxonomy_id: options?.taxonomyId ?? 'tax_usgaap_reporting',
+      description: options?.description ?? 'Map Chart of Accounts to US GAAP reporting concepts',
+    }
+    const envelope = await this.callOperation(
+      'Create mapping structure',
+      opCreateStructure({ path: { graph_id: graphId }, body })
+    )
+    return envelope.result as unknown as LedgerMappingInfo
+  }
+
+  /** Update mutable fields on a structure. `structure_type` is immutable. */
+  async updateStructure(
+    graphId: string,
+    body: UpdateStructureRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update structure',
+      opUpdateStructure({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Soft-delete a structure (`is_active=false`). */
+  async deleteStructure(graphId: string, structureId: string): Promise<Record<string, unknown>> {
+    const body: DeleteStructureRequest = { structure_id: structureId }
+    const envelope = await this.callOperation(
+      'Delete structure',
+      opDeleteStructure({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
   // ── Mappings ────────────────────────────────────────────────────────
 
   /** List active CoA→reporting mapping structures. */
@@ -748,6 +984,42 @@ export class LedgerClient {
     return { operationId: envelope.operationId, status: envelope.status }
   }
 
+  /** Bulk create associations within a single structure, atomically. */
+  async createAssociations(
+    graphId: string,
+    structureId: string,
+    associations: BulkAssociationItem[]
+  ): Promise<Record<string, unknown>> {
+    const body: BulkCreateAssociationsRequest = { structure_id: structureId, associations }
+    const envelope = await this.callOperation(
+      'Create associations',
+      opCreateAssociations({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Update mutable fields on an association (order, weight, confidence). */
+  async updateAssociation(
+    graphId: string,
+    body: UpdateAssociationRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update association',
+      opUpdateAssociation({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Hard-delete an association (any type: presentation, calculation, mapping). */
+  async deleteAssociation(graphId: string, associationId: string): Promise<{ deleted: boolean }> {
+    const body: DeleteAssociationRequest = { association_id: associationId }
+    const envelope = await this.callOperation(
+      'Delete association',
+      opDeleteAssociation({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
+  }
+
   // ── Schedules ──────────────────────────────────────────────────────
 
   /** List all schedule structures with metadata. */
@@ -821,6 +1093,28 @@ export class LedgerClient {
     }
   }
 
+  /** Update mutable fields on a schedule (name, entry_template, metadata). */
+  async updateSchedule(
+    graphId: string,
+    body: UpdateScheduleRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update schedule',
+      opUpdateSchedule({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Permanently delete a schedule (cascades through facts + associations). */
+  async deleteSchedule(graphId: string, structureId: string): Promise<{ deleted: boolean }> {
+    const body: DeleteScheduleRequest = { structure_id: structureId }
+    const envelope = await this.callOperation(
+      'Delete schedule',
+      opDeleteSchedule({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
+  }
+
   /** Truncate a schedule — end it early at `newEndDate`. */
   async truncateSchedule(
     graphId: string,
@@ -1032,7 +1326,105 @@ export class LedgerClient {
     return rawFiscalCalendarToCamel(envelope.result as unknown as RawFiscalCalendar)
   }
 
-  // Reports, statements, and publish lists live on `ReportClient`.
+  // ── Journal entries (native accounting writes) ──────────────────────
+
+  /**
+   * Create a journal entry with balanced line items (DR=CR enforced).
+   *
+   * Defaults to `status='draft'`. Pass `status='posted'` for historical
+   * data import where entries represent already-happened business events.
+   *
+   * Supply `idempotencyKey` to make the call safe to retry — replays
+   * within 24 hours return the same envelope. Reusing the key with a
+   * different body returns HTTP 409.
+   */
+  async createJournalEntry(
+    graphId: string,
+    options: CreateJournalEntryOptions
+  ): Promise<Record<string, unknown>> {
+    const body: CreateJournalEntryRequest = {
+      posting_date: options.postingDate,
+      memo: options.memo,
+      line_items: options.lineItems.map(
+        (li): JournalEntryLineItemInput => ({
+          element_id: li.elementId,
+          debit_amount: li.debitAmount,
+          credit_amount: li.creditAmount,
+          description: li.description ?? null,
+        })
+      ),
+      type: options.type,
+      status: options.status,
+      transaction_id: options.transactionId ?? null,
+    }
+    const envelope = await this.callOperation(
+      'Create journal entry',
+      opCreateJournalEntry({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Update a draft journal entry. Posted entries are immutable. */
+  async updateJournalEntry(
+    graphId: string,
+    body: UpdateJournalEntryRequest
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update journal entry',
+      opUpdateJournalEntry({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Hard-delete a draft journal entry. Posted entries must be reversed. */
+  async deleteJournalEntry(graphId: string, entryId: string): Promise<{ deleted: boolean }> {
+    const body: DeleteJournalEntryRequest = { entry_id: entryId }
+    const envelope = await this.callOperation(
+      'Delete journal entry',
+      opDeleteJournalEntry({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
+  }
+
+  /**
+   * Reverse a posted journal entry — creates an offsetting entry and marks
+   * the original as reversed.
+   */
+  async reverseJournalEntry(
+    graphId: string,
+    entryId: string,
+    options?: { postingDate?: string | null; memo?: string | null }
+  ): Promise<Record<string, unknown>> {
+    const body: ReverseJournalEntryRequest = {
+      entry_id: entryId,
+      posting_date: options?.postingDate ?? null,
+      memo: options?.memo ?? null,
+    }
+    const envelope = await this.callOperation(
+      'Reverse journal entry',
+      opReverseJournalEntry({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  // ── Fact grid (graph-backed analytical query) ─────────────────────
+
+  /**
+   * Build a multi-dimensional fact grid against the graph schema.
+   *
+   * Runs against LadybugDB (not the extensions OLTP database) and returns
+   * a deduplicated pivot table of XBRL facts. Works for both roboledger
+   * tenant graphs (after materialization) and the SEC shared repository.
+   */
+  async buildFactGrid(graphId: string, body: CreateViewRequest): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Build fact grid',
+      opBuildFactGrid({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  // ── Reports, statements, and publish lists ──────────────────────────────
 
   // ── Internal helpers ────────────────────────────────────────────────
 
@@ -1049,7 +1441,7 @@ export class LedgerClient {
   ): Promise<TResult> {
     try {
       const client = this.gql.get(graphId)
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
       const raw = client.request as (doc: unknown, vars?: unknown) => Promise<any>
       // graphql-request's overloads don't cleanly resolve for generic
       // helpers wrapping codegen's `Exact<>` var types, so we bypass
@@ -1064,6 +1456,264 @@ export class LedgerClient {
     }
   }
 
+  // ── Reports ─────────────────────────────────────────────────────────
+
+  /**
+   * Kick off report creation (async). Use the returned `operationId` to
+   * subscribe to progress via SSE, then call `getReport()` once finished.
+   */
+  async createReport(graphId: string, options: CreateReportOptions): Promise<ReportOperationAck> {
+    const body: CreateReportRequest = {
+      name: options.name,
+      mapping_id: options.mappingId,
+      period_start: options.periodStart,
+      period_end: options.periodEnd,
+      taxonomy_id: options.taxonomyId ?? 'tax_usgaap_reporting',
+      period_type: options.periodType ?? 'quarterly',
+      comparative: options.comparative ?? true,
+    }
+    if (options.periods && options.periods.length > 0) {
+      body.periods = options.periods
+    }
+    const envelope = await this.callOperation(
+      'Create report',
+      opCreateReport({ path: { graph_id: graphId }, body })
+    )
+    return {
+      operationId: envelope.operationId,
+      status: envelope.status,
+      result: (envelope.result as Record<string, unknown> | null) ?? null,
+    }
+  }
+
+  /** List all reports for a graph (includes received shared reports). */
+  async listReports(graphId: string): Promise<ReportListItem[]> {
+    const list = await this.gqlQuery(
+      graphId,
+      ListLedgerReportsDocument,
+      undefined,
+      'List reports',
+      (data) => data.reports
+    )
+    return list?.reports ?? []
+  }
+
+  /** Get a single report with its period list + available structures. */
+  async getReport(graphId: string, reportId: string): Promise<Report | null> {
+    return this.gqlQuery(
+      graphId,
+      GetLedgerReportDocument,
+      { reportId },
+      'Get report',
+      (data) => data.report
+    )
+  }
+
+  /**
+   * Render a financial statement — facts viewed through a structure.
+   *
+   * @param structureType - income_statement, balance_sheet, cash_flow_statement
+   */
+  async getStatement(
+    graphId: string,
+    reportId: string,
+    structureType: string
+  ): Promise<StatementData | null> {
+    return this.gqlQuery(
+      graphId,
+      GetLedgerStatementDocument,
+      { reportId, structureType },
+      'Get statement',
+      (data) => data.statement
+    )
+  }
+
+  /**
+   * Regenerate an existing report (async). Returns an operation id;
+   * subscribe via SSE for progress.
+   */
+  async regenerateReport(
+    graphId: string,
+    reportId: string,
+    periodStart?: string,
+    periodEnd?: string
+  ): Promise<ReportOperationAck> {
+    const envelope = await this.callOperation(
+      'Regenerate report',
+      opRegenerateReport({
+        path: { graph_id: graphId },
+        body: {
+          report_id: reportId,
+          period_start: periodStart,
+          period_end: periodEnd,
+        } as Parameters<typeof opRegenerateReport>[0]['body'],
+      })
+    )
+    return {
+      operationId: envelope.operationId,
+      status: envelope.status,
+      result: (envelope.result as Record<string, unknown> | null) ?? null,
+    }
+  }
+
+  /** Delete a report and its generated facts. */
+  async deleteReport(graphId: string, reportId: string): Promise<void> {
+    await this.callOperation(
+      'Delete report',
+      opDeleteReport({
+        path: { graph_id: graphId },
+        body: { report_id: reportId },
+      })
+    )
+  }
+
+  /**
+   * Share a published report to every member of a publish list (async).
+   * Each target graph receives a snapshot copy of the report's facts.
+   */
+  async shareReport(
+    graphId: string,
+    reportId: string,
+    publishListId: string
+  ): Promise<ReportOperationAck> {
+    const envelope = await this.callOperation(
+      'Share report',
+      opShareReport({
+        path: { graph_id: graphId },
+        body: {
+          report_id: reportId,
+          publish_list_id: publishListId,
+        } as Parameters<typeof opShareReport>[0]['body'],
+      })
+    )
+    return {
+      operationId: envelope.operationId,
+      status: envelope.status,
+      result: (envelope.result as Record<string, unknown> | null) ?? null,
+    }
+  }
+
+  /** Check if a report was received via sharing (vs locally created). */
+  isSharedReport(report: Report): boolean {
+    return report.sourceGraphId !== null
+  }
+
+  // ── Publish Lists ────────────────────────────────────────────────────
+
+  /** List publish lists with pagination. */
+  async listPublishLists(
+    graphId: string,
+    options?: { limit?: number; offset?: number }
+  ): Promise<PublishList[]> {
+    const list = await this.gqlQuery(
+      graphId,
+      ListLedgerPublishListsDocument,
+      {
+        limit: options?.limit ?? 100,
+        offset: options?.offset ?? 0,
+      },
+      'List publish lists',
+      (data) => data.publishLists
+    )
+    return list?.publishLists ?? []
+  }
+
+  /** Create a new publish list. */
+  async createPublishList(
+    graphId: string,
+    name: string,
+    description?: string
+  ): Promise<Record<string, unknown>> {
+    const body: CreatePublishListRequest = {
+      name,
+      description: description ?? null,
+    }
+    const envelope = await this.callOperation(
+      'Create publish list',
+      opCreatePublishList({ path: { graph_id: graphId }, body })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Get a single publish list with its full member list. */
+  async getPublishList(graphId: string, listId: string): Promise<PublishListDetail | null> {
+    return this.gqlQuery(
+      graphId,
+      GetLedgerPublishListDocument,
+      { listId },
+      'Get publish list',
+      (data) => data.publishList
+    )
+  }
+
+  /** Update a publish list's name or description. */
+  async updatePublishList(
+    graphId: string,
+    listId: string,
+    updates: { name?: string; description?: string | null }
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Update publish list',
+      opUpdatePublishList({
+        path: { graph_id: graphId },
+        body: {
+          list_id: listId,
+          name: updates.name,
+          description: updates.description ?? null,
+        } as UpdatePublishListOperation,
+      })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Delete a publish list. */
+  async deletePublishList(graphId: string, listId: string): Promise<void> {
+    await this.callOperation(
+      'Delete publish list',
+      opDeletePublishList({
+        path: { graph_id: graphId },
+        body: { list_id: listId },
+      })
+    )
+  }
+
+  /** Add target graphs as members of a publish list. */
+  async addPublishListMembers(
+    graphId: string,
+    listId: string,
+    targetGraphIds: string[]
+  ): Promise<Record<string, unknown>> {
+    const envelope = await this.callOperation(
+      'Add publish list members',
+      opAddPublishListMembers({
+        path: { graph_id: graphId },
+        body: {
+          list_id: listId,
+          target_graph_ids: targetGraphIds,
+        } as AddPublishListMembersOperation,
+      })
+    )
+    return (envelope.result ?? {}) as Record<string, unknown>
+  }
+
+  /** Remove a single member from a publish list. */
+  async removePublishListMember(
+    graphId: string,
+    listId: string,
+    memberId: string
+  ): Promise<{ deleted: boolean }> {
+    const envelope = await this.callOperation(
+      'Remove publish list member',
+      opRemovePublishListMember({
+        path: { graph_id: graphId },
+        body: { list_id: listId, member_id: memberId },
+      })
+    )
+    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
+  }
+
+  // ── Internal helpers ────────────────────────────────────────────────
+
   /**
    * Await an SDK-generated `opXxx(...)` call, throw a readable error on
    * non-2xx, and return the `OperationEnvelope` on success.