@robosystems/client 0.3.38 → 0.3.40

package/artifacts/LedgerClient.d.ts

@@ -1,6 +1,6 @@
 import type { AssociationResponse, AutoMapElementsOperation, CreateAgentRequest, CreateEventBlockRequest, CreateEventHandlerRequest, CreateInformationBlockRequest, CreateMappingAssociationOperation, CreateTaxonomyBlockRequest, CreateViewRequest, DeleteInformationBlockRequest, DeleteInformationBlockResponse, DeleteMappingAssociationOperation, DeleteResult, DeleteTaxonomyBlockRequest, DeleteTaxonomyBlockResponse, EntityTaxonomyResponse, EvaluateRulesRequest, EvaluateRulesResponse, EventBlockEnvelope, EventHandlerResponse, FinancialStatementAnalysisRequest, InformationBlockEnvelope, JournalEntryResponse, LedgerAgentResponse, LinkEntityTaxonomyRequest, LiveFinancialStatementRequest, OperationEnvelope, PreviewEventBlockResponse, PublishListMemberResponse, PublishListResponse, ReportResponse, ShareReportResponse, TaxonomyBlockEnvelope, UpdateAgentRequest, UpdateEntityRequest, UpdateEventBlockRequest, UpdateEventHandlerRequest, UpdateInformationBlockRequest, UpdateJournalEntryRequest, UpdateTaxonomyBlockRequest } from '../types.gen';
 import type { TokenProvider } from './graphql/client';
-import { type GetInformationBlockQuery, type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerAgentQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerEventBlockQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerPublishListQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerReportPackageQuery, type GetLedgerReportQuery, type GetLedgerStatementQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListInformationBlocksQuery, type ListLedgerAccountsQuery, type ListLedgerAgentsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerEventBlocksQuery, type ListLedgerMappingsQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery, type MappingCandidatesQuery } from './graphql/generated/graphql';
+import { type GetInformationBlockQuery, type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerAgentQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerEventBlockQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerPublishListQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerReportPackageQuery, type GetLedgerReportQuery, type GetLedgerStatementQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListInformationBlocksQuery, type ListLedgerAccountsQuery, type ListLedgerAgentsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerEventBlocksQuery, type ListLedgerMappingsQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery, type MappingCandidatesQuery, type ReportDownloadFormat } from './graphql/generated/graphql';
 export type LedgerEntity = NonNullable<GetLedgerEntityQuery['entity']>;
 export type LedgerEntitySummary = ListLedgerEntitiesQuery['entities'][number];
 export type LedgerSummary = NonNullable<GetLedgerSummaryQuery['summary']>;
@@ -56,7 +56,7 @@ export type PublishListMember = PublishListDetail['members'][number];
 /**
  * Presigned-URL response for a Report bundle download.
  *
- * Returned by ``LedgerClient.getReportBundleDownloadUrl`` — the
+ * Returned by ``LedgerClient.getReportDownloadUrl`` — the
  * ``downloadUrl`` is a time-limited URL that streams the
  * serialization artifact directly from object storage. Browser
  * callers typically follow the URL via ``window.location.href`` or
@@ -69,7 +69,7 @@ export interface ReportBundleDownloadResponse {
     expiresAt: string;
     /** MIME type of the artifact behind the URL. */
     contentType: string;
-    /** Serialization flavor — ``jsonld`` is the Phase 1a default. */
+    /** Serialization flavor — ``jsonld`` or ``xbrl-2.1``. */
     format: string;
     /** Bundle generation number stamped on the Report. */
     generationCount: number;
@@ -587,51 +587,29 @@ export declare class LedgerClient {
      * Get a short-lived presigned URL for downloading a published
      * Report's serialization bundle.
      *
-     * Phase 1a only resolves the JSON-LD flavor; reserved RDF and XBRL
-     * flavors return HTTP 400 until their producers ship. Reports
-     * published before the serialization feature shipped will resolve
-     * to a 404 — those Reports have no stamped bundle_url and must be
-     * regenerated to produce one.
+     * A download is a read, so this resolves through GraphQL
+     * (`reportDownloadUrl`) — the retired `GET .../reports/{id}/download`
+     * REST resource is gone. Every flavor resolves to a presigned S3 URL:
+     * JSON-LD is stamped at publish time; XBRL is materialized + cached
+     * on first request. The returned `downloadUrl` is valid for
+     * `expiresIn` seconds (default 300, max 3600); browser callers
+     * navigate to it via `window.location.href` (or an `<a href>` click)
+     * to trigger the download — the server-set Content-Disposition forces
+     * "attachment" with a versioned filename.
      *
-     * The returned ``downloadUrl`` is a presigned S3 URL valid for
-     * ``expiresIn`` seconds (default 300, max 3600). Browser callers
-     * typically navigate to it via ``window.location.href`` (or assign
-     * to an `<a href>` and click) to trigger the file download; the
-     * server-set Content-Disposition forces "attachment" with a
-     * versioned filename.
+     * Returns `null` when the report doesn't exist. A report that has
+     * never been published surfaces a `REPORT_BUNDLE_NOT_AVAILABLE`
+     * GraphQL error (regenerate it to produce a bundle).
      *
      * @param graphId Graph identifier owning the Report.
      * @param reportId Report identifier (rpt_-prefixed ULID).
-     * @param options.format Serialization flavor — defaults to ``'jsonld'``.
+     * @param options.format Serialization flavor — `JSONLD` (default) or `XBRL_2_1`.
      * @param options.expiresIn Presigned URL lifetime, in seconds.
      */
-    getReportBundleDownloadUrl(graphId: string, reportId: string, options?: {
-        format?: string;
+    getReportDownloadUrl(graphId: string, reportId: string, options?: {
+        format?: ReportDownloadFormat;
         expiresIn?: number;
-    }): Promise<ReportBundleDownloadResponse>;
-    /**
-     * Download the Report's serialization bundle as an XBRL 2.1 zip.
-     *
-     * Rebuilds the bundle on the server and streams the zip body
-     * directly — no S3 presigned URL is involved (XBRL is on-demand
-     * emit, per the serialization spec). The returned ``Blob`` can be
-     * saved via URL.createObjectURL + a temporary anchor click to
-     * trigger the browser download dialog.
-     *
-     * The zip contains five files: ``instance.xml``, ``report.xsd``,
-     * ``report-pre.xml``, ``report-cal.xml``, ``report-def.xml``.
-     *
-     * @param graphId Graph identifier owning the Report.
-     * @param reportId Report identifier (rpt_-prefixed ULID).
-     * @param options.flavor XBRL flavor (default ``'xbrl-2.1'``).
-     */
-    getReportBundleXbrlZip(graphId: string, reportId: string, options?: {
-        flavor?: string;
-    }): Promise<{
-        blob: Blob;
-        filename: string;
-        generationCount: number | null;
-    }>;
+    }): Promise<ReportBundleDownloadResponse | null>;
     /**
      * Share a published report to every member of a publish list. Each
      * target graph receives a snapshot copy of the report's facts.

package/artifacts/LedgerClient.js

@@ -768,115 +768,42 @@ class LedgerClient {
      * Get a short-lived presigned URL for downloading a published
      * Report's serialization bundle.
      *
-     * Phase 1a only resolves the JSON-LD flavor; reserved RDF and XBRL
-     * flavors return HTTP 400 until their producers ship. Reports
-     * published before the serialization feature shipped will resolve
-     * to a 404 — those Reports have no stamped bundle_url and must be
-     * regenerated to produce one.
+     * A download is a read, so this resolves through GraphQL
+     * (`reportDownloadUrl`) — the retired `GET .../reports/{id}/download`
+     * REST resource is gone. Every flavor resolves to a presigned S3 URL:
+     * JSON-LD is stamped at publish time; XBRL is materialized + cached
+     * on first request. The returned `downloadUrl` is valid for
+     * `expiresIn` seconds (default 300, max 3600); browser callers
+     * navigate to it via `window.location.href` (or an `<a href>` click)
+     * to trigger the download — the server-set Content-Disposition forces
+     * "attachment" with a versioned filename.
      *
-     * The returned ``downloadUrl`` is a presigned S3 URL valid for
-     * ``expiresIn`` seconds (default 300, max 3600). Browser callers
-     * typically navigate to it via ``window.location.href`` (or assign
-     * to an `<a href>` and click) to trigger the file download; the
-     * server-set Content-Disposition forces "attachment" with a
-     * versioned filename.
+     * Returns `null` when the report doesn't exist. A report that has
+     * never been published surfaces a `REPORT_BUNDLE_NOT_AVAILABLE`
+     * GraphQL error (regenerate it to produce a bundle).
      *
      * @param graphId Graph identifier owning the Report.
      * @param reportId Report identifier (rpt_-prefixed ULID).
-     * @param options.format Serialization flavor — defaults to ``'jsonld'``.
+     * @param options.format Serialization flavor — `JSONLD` (default) or `XBRL_2_1`.
      * @param options.expiresIn Presigned URL lifetime, in seconds.
      */
-    async getReportBundleDownloadUrl(graphId, reportId, options = {}) {
-        const format = options.format ?? 'jsonld';
-        const expiresIn = options.expiresIn ?? 300;
-        const url = `${this.config.baseUrl.replace(/\/$/, '')}` +
-            `/extensions/roboledger/${encodeURIComponent(graphId)}` +
-            `/reports/${encodeURIComponent(reportId)}/download` +
-            `?format=${encodeURIComponent(format)}&expires_in=${expiresIn}`;
-        const headers = new Headers({ Accept: 'application/json', ...(this.config.headers ?? {}) });
-        const token = await this.resolveToken();
-        if (token) {
-            // ``rfs…`` long-lived keys go in X-API-Key; everything else is
-            // a short-lived JWT. Mirrors the GraphQL client behaviour at
-            // ``clients/graphql/client.ts``.
-            if (token.startsWith('rfs')) {
-                headers.set('X-API-Key', token);
-            }
-            else {
-                headers.set('Authorization', `Bearer ${token}`);
-            }
-        }
-        const response = await fetch(url, {
-            method: 'GET',
-            headers,
-            credentials: this.config.credentials,
-        });
-        if (!response.ok) {
-            const body = await response.text();
-            throw new Error(`Get report bundle download URL failed (${response.status}): ${body}`);
-        }
-        const raw = (await response.json());
-        return {
-            downloadUrl: raw.download_url,
-            expiresAt: raw.expires_at,
-            contentType: raw.content_type,
-            format: raw.format,
-            generationCount: raw.generation_count,
-        };
-    }
-    /**
-     * Download the Report's serialization bundle as an XBRL 2.1 zip.
-     *
-     * Rebuilds the bundle on the server and streams the zip body
-     * directly — no S3 presigned URL is involved (XBRL is on-demand
-     * emit, per the serialization spec). The returned ``Blob`` can be
-     * saved via URL.createObjectURL + a temporary anchor click to
-     * trigger the browser download dialog.
-     *
-     * The zip contains five files: ``instance.xml``, ``report.xsd``,
-     * ``report-pre.xml``, ``report-cal.xml``, ``report-def.xml``.
-     *
-     * @param graphId Graph identifier owning the Report.
-     * @param reportId Report identifier (rpt_-prefixed ULID).
-     * @param options.flavor XBRL flavor (default ``'xbrl-2.1'``).
-     */
-    async getReportBundleXbrlZip(graphId, reportId, options = {}) {
-        const flavor = options.flavor ?? 'xbrl-2.1';
-        const url = `${this.config.baseUrl.replace(/\/$/, '')}` +
-            `/extensions/roboledger/${encodeURIComponent(graphId)}` +
-            `/reports/${encodeURIComponent(reportId)}/download` +
-            `?format=${encodeURIComponent(flavor)}`;
-        const headers = new Headers({
-            Accept: 'application/zip',
-            ...(this.config.headers ?? {}),
-        });
-        const token = await this.resolveToken();
-        if (token) {
-            if (token.startsWith('rfs')) {
-                headers.set('X-API-Key', token);
-            }
-            else {
-                headers.set('Authorization', `Bearer ${token}`);
-            }
-        }
-        const response = await fetch(url, {
-            method: 'GET',
-            headers,
-            credentials: this.config.credentials,
+    async getReportDownloadUrl(graphId, reportId, options = {}) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerReportDownloadUrlDocument, {
+            reportId,
+            format: options.format ?? 'JSONLD',
+            expiresIn: options.expiresIn ?? 300,
+        }, 'Get report download URL', (data) => {
+            const node = data.reportDownloadUrl;
+            if (!node)
+                return null;
+            return {
+                downloadUrl: node.downloadUrl,
+                expiresAt: node.expiresAt,
+                contentType: node.contentType,
+                format: node.format,
+                generationCount: node.generationCount,
+            };
         });
-        if (!response.ok) {
-            const body = await response.text();
-            throw new Error(`Get report bundle XBRL zip failed (${response.status}): ${body}`);
-        }
-        const blob = await response.blob();
-        // Parse Content-Disposition for the server-suggested filename;
-        // fall back to a sensible default if absent.
-        const disposition = response.headers.get('Content-Disposition') ?? '';
-        const filenameMatch = disposition.match(/filename="?([^";]+)"?/i);
-        const filename = filenameMatch ? filenameMatch[1] : `${reportId}.zip`;
-        const generationHeader = response.headers.get('X-Bundle-Generation');
-        const generationCount = generationHeader ? Number.parseInt(generationHeader, 10) : null;
-        return { blob, filename, generationCount };
     }
     /**
      * Share a published report to every member of a publish list. Each

package/artifacts/LedgerClient.ts

@@ -136,6 +136,7 @@ import {
   GetLedgerPeriodDraftsDocument,
   GetLedgerPublishListDocument,
   GetLedgerReportDocument,
+  GetLedgerReportDownloadUrlDocument,
   GetLedgerReportingTaxonomyDocument,
   GetLedgerReportPackageDocument,
   GetLedgerStatementDocument,
@@ -191,6 +192,7 @@ import {
   type ListLedgerTransactionsQuery,
   type ListLedgerUnmappedElementsQuery,
   type MappingCandidatesQuery,
+  type ReportDownloadFormat,
 } from './graphql/generated/graphql'
 
 // ── Friendly types derived from GraphQL codegen ────────────────────────
@@ -283,7 +285,7 @@ export type PublishListMember = PublishListDetail['members'][number]
 /**
  * Presigned-URL response for a Report bundle download.
  *
- * Returned by ``LedgerClient.getReportBundleDownloadUrl`` — the
+ * Returned by ``LedgerClient.getReportDownloadUrl`` — the
  * ``downloadUrl`` is a time-limited URL that streams the
  * serialization artifact directly from object storage. Browser
  * callers typically follow the URL via ``window.location.href`` or
@@ -296,20 +298,12 @@ export interface ReportBundleDownloadResponse {
   expiresAt: string
   /** MIME type of the artifact behind the URL. */
   contentType: string
-  /** Serialization flavor — ``jsonld`` is the Phase 1a default. */
+  /** Serialization flavor — ``jsonld`` or ``xbrl-2.1``. */
   format: string
   /** Bundle generation number stamped on the Report. */
   generationCount: number
 }
 
-interface RawReportBundleDownloadResponse {
-  download_url: string
-  expires_at: string
-  content_type: string
-  format: string
-  generation_count: number
-}
-
 export interface PeriodSpecInput {
   start: string
   end: string
@@ -1903,124 +1897,51 @@ export class LedgerClient {
    * Get a short-lived presigned URL for downloading a published
    * Report's serialization bundle.
    *
-   * Phase 1a only resolves the JSON-LD flavor; reserved RDF and XBRL
-   * flavors return HTTP 400 until their producers ship. Reports
-   * published before the serialization feature shipped will resolve
-   * to a 404 — those Reports have no stamped bundle_url and must be
-   * regenerated to produce one.
+   * A download is a read, so this resolves through GraphQL
+   * (`reportDownloadUrl`) — the retired `GET .../reports/{id}/download`
+   * REST resource is gone. Every flavor resolves to a presigned S3 URL:
+   * JSON-LD is stamped at publish time; XBRL is materialized + cached
+   * on first request. The returned `downloadUrl` is valid for
+   * `expiresIn` seconds (default 300, max 3600); browser callers
+   * navigate to it via `window.location.href` (or an `<a href>` click)
+   * to trigger the download — the server-set Content-Disposition forces
+   * "attachment" with a versioned filename.
    *
-   * The returned ``downloadUrl`` is a presigned S3 URL valid for
-   * ``expiresIn`` seconds (default 300, max 3600). Browser callers
-   * typically navigate to it via ``window.location.href`` (or assign
-   * to an `<a href>` and click) to trigger the file download; the
-   * server-set Content-Disposition forces "attachment" with a
-   * versioned filename.
+   * Returns `null` when the report doesn't exist. A report that has
+   * never been published surfaces a `REPORT_BUNDLE_NOT_AVAILABLE`
+   * GraphQL error (regenerate it to produce a bundle).
    *
    * @param graphId Graph identifier owning the Report.
    * @param reportId Report identifier (rpt_-prefixed ULID).
-   * @param options.format Serialization flavor — defaults to ``'jsonld'``.
+   * @param options.format Serialization flavor — `JSONLD` (default) or `XBRL_2_1`.
    * @param options.expiresIn Presigned URL lifetime, in seconds.
    */
-  async getReportBundleDownloadUrl(
-    graphId: string,
-    reportId: string,
-    options: { format?: string; expiresIn?: number } = {}
-  ): Promise<ReportBundleDownloadResponse> {
-    const format = options.format ?? 'jsonld'
-    const expiresIn = options.expiresIn ?? 300
-    const url =
-      `${this.config.baseUrl.replace(/\/$/, '')}` +
-      `/extensions/roboledger/${encodeURIComponent(graphId)}` +
-      `/reports/${encodeURIComponent(reportId)}/download` +
-      `?format=${encodeURIComponent(format)}&expires_in=${expiresIn}`
-    const headers = new Headers({ Accept: 'application/json', ...(this.config.headers ?? {}) })
-    const token = await this.resolveToken()
-    if (token) {
-      // ``rfs…`` long-lived keys go in X-API-Key; everything else is
-      // a short-lived JWT. Mirrors the GraphQL client behaviour at
-      // ``clients/graphql/client.ts``.
-      if (token.startsWith('rfs')) {
-        headers.set('X-API-Key', token)
-      } else {
-        headers.set('Authorization', `Bearer ${token}`)
-      }
-    }
-    const response = await fetch(url, {
-      method: 'GET',
-      headers,
-      credentials: this.config.credentials,
-    })
-    if (!response.ok) {
-      const body = await response.text()
-      throw new Error(`Get report bundle download URL failed (${response.status}): ${body}`)
-    }
-    const raw = (await response.json()) as RawReportBundleDownloadResponse
-    return {
-      downloadUrl: raw.download_url,
-      expiresAt: raw.expires_at,
-      contentType: raw.content_type,
-      format: raw.format,
-      generationCount: raw.generation_count,
-    }
-  }
-
-  /**
-   * Download the Report's serialization bundle as an XBRL 2.1 zip.
-   *
-   * Rebuilds the bundle on the server and streams the zip body
-   * directly — no S3 presigned URL is involved (XBRL is on-demand
-   * emit, per the serialization spec). The returned ``Blob`` can be
-   * saved via URL.createObjectURL + a temporary anchor click to
-   * trigger the browser download dialog.
-   *
-   * The zip contains five files: ``instance.xml``, ``report.xsd``,
-   * ``report-pre.xml``, ``report-cal.xml``, ``report-def.xml``.
-   *
-   * @param graphId Graph identifier owning the Report.
-   * @param reportId Report identifier (rpt_-prefixed ULID).
-   * @param options.flavor XBRL flavor (default ``'xbrl-2.1'``).
-   */
-  async getReportBundleXbrlZip(
+  async getReportDownloadUrl(
     graphId: string,
     reportId: string,
-    options: { flavor?: string } = {}
-  ): Promise<{ blob: Blob; filename: string; generationCount: number | null }> {
-    const flavor = options.flavor ?? 'xbrl-2.1'
-    const url =
-      `${this.config.baseUrl.replace(/\/$/, '')}` +
-      `/extensions/roboledger/${encodeURIComponent(graphId)}` +
-      `/reports/${encodeURIComponent(reportId)}/download` +
-      `?format=${encodeURIComponent(flavor)}`
-    const headers = new Headers({
-      Accept: 'application/zip',
-      ...(this.config.headers ?? {}),
-    })
-    const token = await this.resolveToken()
-    if (token) {
-      if (token.startsWith('rfs')) {
-        headers.set('X-API-Key', token)
-      } else {
-        headers.set('Authorization', `Bearer ${token}`)
+    options: { format?: ReportDownloadFormat; expiresIn?: number } = {}
+  ): Promise<ReportBundleDownloadResponse | null> {
+    return this.gqlQuery(
+      graphId,
+      GetLedgerReportDownloadUrlDocument,
+      {
+        reportId,
+        format: options.format ?? 'JSONLD',
+        expiresIn: options.expiresIn ?? 300,
+      },
+      'Get report download URL',
+      (data) => {
+        const node = data.reportDownloadUrl
+        if (!node) return null
+        return {
+          downloadUrl: node.downloadUrl,
+          expiresAt: node.expiresAt,
+          contentType: node.contentType,
+          format: node.format,
+          generationCount: node.generationCount,
+        }
       }
-    }
-    const response = await fetch(url, {
-      method: 'GET',
-      headers,
-      credentials: this.config.credentials,
-    })
-    if (!response.ok) {
-      const body = await response.text()
-      throw new Error(`Get report bundle XBRL zip failed (${response.status}): ${body}`)
-    }
-    const blob = await response.blob()
-    // Parse Content-Disposition for the server-suggested filename;
-    // fall back to a sensible default if absent.
-    const disposition = response.headers.get('Content-Disposition') ?? ''
-    const filenameMatch = disposition.match(/filename="?([^";]+)"?/i)
-    const filename = filenameMatch ? filenameMatch[1] : `${reportId}.zip`
-    const generationHeader = response.headers.get('X-Bundle-Generation')
-    const generationCount = generationHeader ? Number.parseInt(generationHeader, 10) : null
-    return { blob, filename, generationCount }
+    )
   }
 
   /**

package/artifacts/LibraryClient.d.ts

@@ -1,5 +1,5 @@
 import type { TokenProvider } from './graphql/client';
-import { type GetLibraryElementArcsQuery, type GetLibraryElementClassificationsQuery, type GetLibraryElementEquivalentsQuery, type GetLibraryElementQuery, type GetLibraryTaxonomyQuery, type ListLibraryElementsQuery, type ListLibraryTaxonomiesQuery, type ListLibraryTaxonomyArcsQuery, type SearchLibraryElementsQuery } from './graphql/generated/graphql';
+import { type GetLibraryElementArcsQuery, type GetLibraryElementClassificationsQuery, type GetLibraryElementEquivalentsQuery, type GetLibraryElementQuery, type GetLibraryTaxonomyQuery, type ListLibraryElementsQuery, type ListLibraryStructuresQuery, type ListLibraryTaxonomiesQuery, type ListLibraryTaxonomyArcsQuery, type SearchLibraryElementsQuery } from './graphql/generated/graphql';
 export type LibraryTaxonomy = ListLibraryTaxonomiesQuery['libraryTaxonomies'][number];
 export type LibraryTaxonomyDetail = NonNullable<GetLibraryTaxonomyQuery['libraryTaxonomy']>;
 export type LibraryElement = ListLibraryElementsQuery['libraryElements'][number];
@@ -8,6 +8,7 @@ export type LibrarySearchResult = SearchLibraryElementsQuery['searchLibraryEleme
 export type LibraryLabel = LibraryElementDetail['labels'][number];
 export type LibraryReference = LibraryElementDetail['references'][number];
 export type LibraryArc = ListLibraryTaxonomyArcsQuery['libraryTaxonomyArcs'][number];
+export type LibraryStructure = ListLibraryStructuresQuery['libraryStructures'][number];
 export type LibraryElementArc = GetLibraryElementArcsQuery['libraryElementArcs'][number];
 export type LibraryElementClassification = GetLibraryElementClassificationsQuery['libraryElementClassifications'][number];
 export type LibraryEquivalence = NonNullable<GetLibraryElementEquivalentsQuery['libraryElementEquivalents']>;
@@ -32,6 +33,8 @@ export interface SearchLibraryElementsOptions {
 }
 export interface ListLibraryTaxonomyArcsOptions {
     associationType?: string;
+    /** Scope to a single structure (one presentation/calculation hierarchy). */
+    structureId?: string;
     limit?: number;
     offset?: number;
 }
@@ -39,6 +42,11 @@ export interface ListLibraryTaxonomyArcsResult {
     arcs: LibraryArc[];
     count: number;
 }
+export interface ListLibraryStructuresOptions {
+    taxonomyId?: string;
+    /** Filter to one statement kind (balance_sheet | income_statement | …). */
+    blockType?: string;
+}
 export interface GetLibraryElementIdentifier {
     id?: string;
     qname?: string;
@@ -102,6 +110,15 @@ export declare class LibraryClient {
      * type-subtype) this is the primary browse view.
      */
     listLibraryTaxonomyArcs(graphId: string, taxonomyId: string, options?: ListLibraryTaxonomyArcsOptions): Promise<ListLibraryTaxonomyArcsResult>;
+    /**
+     * List the structures (extended link roles) a taxonomy contributes —
+     * the named presentation/calculation hierarchies (BS-classified,
+     * IS-multistep, the calc DAG roots, …). Pair a structure's `id` with
+     * `listLibraryTaxonomyArcs({ structureId })` to load just that
+     * hierarchy's arcs — the hierarchy view uses this to scope a tree to
+     * one role at a time.
+     */
+    listLibraryStructures(graphId: string, options?: ListLibraryStructuresOptions): Promise<LibraryStructure[]>;
     /**
      * All mapping arcs where this element is source or target. Covers
      * every `taxonomy_type='mapping'` bridge — equivalence,

package/artifacts/LibraryClient.js

@@ -87,6 +87,7 @@ class LibraryClient {
         return this.gqlQuery(graphId, graphql_1.ListLibraryTaxonomyArcsDocument, {
             taxonomyId,
             associationType: options?.associationType ?? null,
+            structureId: options?.structureId ?? null,
             limit: options?.limit ?? 200,
             offset: options?.offset ?? 0,
         }, 'List library taxonomy arcs', (data) => ({
@@ -94,6 +95,21 @@ class LibraryClient {
             count: data.libraryTaxonomyArcCount,
         }));
     }
+    // ── Structures ───────────────────────────────────────────────────────
+    /**
+     * List the structures (extended link roles) a taxonomy contributes —
+     * the named presentation/calculation hierarchies (BS-classified,
+     * IS-multistep, the calc DAG roots, …). Pair a structure's `id` with
+     * `listLibraryTaxonomyArcs({ structureId })` to load just that
+     * hierarchy's arcs — the hierarchy view uses this to scope a tree to
+     * one role at a time.
+     */
+    async listLibraryStructures(graphId, options) {
+        return this.gqlQuery(graphId, graphql_1.ListLibraryStructuresDocument, {
+            taxonomyId: options?.taxonomyId ?? null,
+            blockType: options?.blockType ?? null,
+        }, 'List library structures', (data) => data.libraryStructures);
+    }
     /**
      * All mapping arcs where this element is source or target. Covers
      * every `taxonomy_type='mapping'` bridge — equivalence,

package/artifacts/LibraryClient.ts

@@ -37,6 +37,7 @@ import {
   GetLibraryElementEquivalentsDocument,
   GetLibraryTaxonomyDocument,
   ListLibraryElementsDocument,
+  ListLibraryStructuresDocument,
   ListLibraryTaxonomiesDocument,
   ListLibraryTaxonomyArcsDocument,
   SearchLibraryElementsDocument,
@@ -46,6 +47,7 @@ import {
   type GetLibraryElementQuery,
   type GetLibraryTaxonomyQuery,
   type ListLibraryElementsQuery,
+  type ListLibraryStructuresQuery,
   type ListLibraryTaxonomiesQuery,
   type ListLibraryTaxonomyArcsQuery,
   type SearchLibraryElementsQuery,
@@ -67,6 +69,7 @@ export type LibraryLabel = LibraryElementDetail['labels'][number]
 export type LibraryReference = LibraryElementDetail['references'][number]
 
 export type LibraryArc = ListLibraryTaxonomyArcsQuery['libraryTaxonomyArcs'][number]
+export type LibraryStructure = ListLibraryStructuresQuery['libraryStructures'][number]
 export type LibraryElementArc = GetLibraryElementArcsQuery['libraryElementArcs'][number]
 export type LibraryElementClassification =
   GetLibraryElementClassificationsQuery['libraryElementClassifications'][number]
@@ -99,6 +102,8 @@ export interface SearchLibraryElementsOptions {
 
 export interface ListLibraryTaxonomyArcsOptions {
   associationType?: string
+  /** Scope to a single structure (one presentation/calculation hierarchy). */
+  structureId?: string
   limit?: number
   offset?: number
 }
@@ -108,6 +113,12 @@ export interface ListLibraryTaxonomyArcsResult {
   count: number
 }
 
+export interface ListLibraryStructuresOptions {
+  taxonomyId?: string
+  /** Filter to one statement kind (balance_sheet | income_statement | …). */
+  blockType?: string
+}
+
 export interface GetLibraryElementIdentifier {
   id?: string
   qname?: string
@@ -276,6 +287,7 @@ export class LibraryClient {
       {
         taxonomyId,
         associationType: options?.associationType ?? null,
+        structureId: options?.structureId ?? null,
         limit: options?.limit ?? 200,
         offset: options?.offset ?? 0,
       },
@@ -287,6 +299,32 @@ export class LibraryClient {
     )
   }
 
+  // ── Structures ───────────────────────────────────────────────────────
+
+  /**
+   * List the structures (extended link roles) a taxonomy contributes —
+   * the named presentation/calculation hierarchies (BS-classified,
+   * IS-multistep, the calc DAG roots, …). Pair a structure's `id` with
+   * `listLibraryTaxonomyArcs({ structureId })` to load just that
+   * hierarchy's arcs — the hierarchy view uses this to scope a tree to
+   * one role at a time.
+   */
+  async listLibraryStructures(
+    graphId: string,
+    options?: ListLibraryStructuresOptions
+  ): Promise<LibraryStructure[]> {
+    return this.gqlQuery(
+      graphId,
+      ListLibraryStructuresDocument,
+      {
+        taxonomyId: options?.taxonomyId ?? null,
+        blockType: options?.blockType ?? null,
+      },
+      'List library structures',
+      (data) => data.libraryStructures
+    )
+  }
+
   /**
    * All mapping arcs where this element is source or target. Covers
    * every `taxonomy_type='mapping'` bridge — equivalence,