@robosystems/client 0.3.13 → 0.3.15

package/artifacts/InvestorClient.ts

@@ -3,14 +3,20 @@
 /**
  * Investor Client for RoboSystems API
  *
- * High-level facade for the RoboInvestor domain: portfolios, securities,
- * positions, and portfolio holdings aggregation. Follows the same
- * hybrid transport pattern as `LedgerClient`:
+ * High-level facade for the RoboInvestor domain: portfolios (via the
+ * Portfolio Block molecule), securities (Master Data CRUD), positions
+ * (folded into Portfolio Block writes), and portfolio holdings
+ * aggregation. Same hybrid transport pattern as `LedgerClient`:
  *
  * - **Reads** go through GraphQL at `/extensions/{graph_id}/graphql`.
  * - **Writes** go through named operations at
  *   `/extensions/roboinvestor/{graph_id}/operations/{operation_name}`.
  *
+ * Portfolio + position writes flow through the **Portfolio Block**
+ * envelope ops (`create-portfolio-block`, `update-portfolio-block`,
+ * `delete-portfolio-block`); atom-level CRUD on portfolios/positions
+ * has been retired. Securities remain Master Data CRUD.
+ *
  * Every write returns an `OperationEnvelope`; this facade unwraps
  * `envelope.result` and returns a typed shape derived from the GraphQL
  * codegen output (which is the source of truth for read payload types).
@@ -19,37 +25,35 @@
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core'
 import { ClientError } from 'graphql-request'
 import {
-  opCreatePortfolio,
-  opCreatePosition,
+  opCreatePortfolioBlock,
   opCreateSecurity,
-  opDeletePortfolio,
-  opDeletePosition,
+  opDeletePortfolioBlock,
   opDeleteSecurity,
-  opUpdatePortfolio,
-  opUpdatePosition,
+  opUpdatePortfolioBlock,
   opUpdateSecurity,
 } from '../sdk.gen'
 import type {
-  CreatePortfolioRequest,
-  CreatePositionRequest,
+  CreatePortfolioBlockRequest,
   CreateSecurityRequest,
+  DeletePortfolioBlockOperation,
   OperationEnvelope,
-  UpdatePortfolioOperation,
-  UpdatePositionOperation,
+  PortfolioBlockPortfolioPatch,
+  PortfolioBlockPositions,
+  UpdatePortfolioBlockOperation,
   UpdateSecurityOperation,
 } from '../types.gen'
 import type { TokenProvider } from './graphql/client'
 import { GraphQLClientCache } from './graphql/client'
 import {
   GetInvestorHoldingsDocument,
-  GetInvestorPortfolioDocument,
+  GetInvestorPortfolioBlockDocument,
   GetInvestorPositionDocument,
   GetInvestorSecurityDocument,
   ListInvestorPortfoliosDocument,
   ListInvestorPositionsDocument,
   ListInvestorSecuritiesDocument,
   type GetInvestorHoldingsQuery,
-  type GetInvestorPortfolioQuery,
+  type GetInvestorPortfolioBlockQuery,
   type GetInvestorPositionQuery,
   type GetInvestorSecurityQuery,
   type ListInvestorPortfoliosQuery,
@@ -61,7 +65,11 @@ import {
 
 export type InvestorPortfolioList = NonNullable<ListInvestorPortfoliosQuery['portfolios']>
 export type InvestorPortfolioSummary = InvestorPortfolioList['portfolios'][number]
-export type InvestorPortfolio = NonNullable<GetInvestorPortfolioQuery['portfolio']>
+
+export type InvestorPortfolioBlock = NonNullable<GetInvestorPortfolioBlockQuery['portfolioBlock']>
+export type InvestorPositionBlock = InvestorPortfolioBlock['positions'][number]
+export type InvestorSecurityLite = InvestorPositionBlock['security']
+export type InvestorEntityLite = InvestorPortfolioBlock['owner']
 
 export type InvestorSecurityList = NonNullable<ListInvestorSecuritiesQuery['securities']>
 export type InvestorSecuritySummary = InvestorSecurityList['securities'][number]
@@ -99,7 +107,7 @@ export class InvestorClient {
     this.gql = new GraphQLClientCache(config)
   }
 
-  // ── Portfolios ──────────────────────────────────────────────────────
+  // ── Portfolios (reads) ──────────────────────────────────────────────
 
   /** List portfolios with pagination. */
   async listPortfolios(
@@ -118,56 +126,85 @@ export class InvestorClient {
     )
   }
 
-  /** Get a single portfolio by id. Returns null if it doesn't exist. */
-  async getPortfolio(graphId: string, portfolioId: string): Promise<InvestorPortfolio | null> {
+  /**
+   * Get the Portfolio Block — molecule envelope with portfolio,
+   * positions, securities, and entity references in a single read.
+   * Returns null if the portfolio doesn't exist.
+   */
+  async getPortfolioBlock(
+    graphId: string,
+    portfolioId: string
+  ): Promise<InvestorPortfolioBlock | null> {
     return this.gqlQuery(
       graphId,
-      GetInvestorPortfolioDocument,
+      GetInvestorPortfolioBlockDocument,
       { portfolioId },
-      'Get portfolio',
-      (data) => data.portfolio
+      'Get portfolio block',
+      (data) => data.portfolioBlock
     )
   }
 
-  /** Create a new portfolio. Returns the created portfolio. */
-  async createPortfolio(graphId: string, body: CreatePortfolioRequest): Promise<InvestorPortfolio> {
+  // ── Portfolio Block (writes) ────────────────────────────────────────
+
+  /**
+   * Create a portfolio (with optional initial positions) atomically.
+   * Each position references an existing security; this op never mints
+   * securities — use `createSecurity` first.
+   */
+  async createPortfolioBlock(
+    graphId: string,
+    body: CreatePortfolioBlockRequest
+  ): Promise<InvestorPortfolioBlock> {
     const envelope = await this.callOperation(
-      'Create portfolio',
-      opCreatePortfolio({ path: { graph_id: graphId }, body })
+      'Create portfolio block',
+      opCreatePortfolioBlock({ path: { graph_id: graphId }, body })
     )
-    return rawToInvestorPortfolio(envelope.result as unknown as RawPortfolioResponse)
+    return rawToPortfolioBlock(envelope.result as unknown as RawPortfolioBlockResponse)
   }
 
-  /** Update a portfolio's metadata. Only provided fields are applied. */
-  async updatePortfolio(
+  /**
+   * Patch portfolio fields and apply position deltas (`add`, `update`,
+   * `dispose`) atomically. All deltas roll back together on failure.
+   * Pass only the fields/deltas you want changed — anything omitted
+   * is left untouched.
+   */
+  async updatePortfolioBlock(
     graphId: string,
     portfolioId: string,
-    updates: Omit<UpdatePortfolioOperation, 'portfolio_id'>
-  ): Promise<InvestorPortfolio> {
+    updates: {
+      portfolio?: PortfolioBlockPortfolioPatch
+      positions?: PortfolioBlockPositions
+    }
+  ): Promise<InvestorPortfolioBlock> {
+    const body: UpdatePortfolioBlockOperation = {
+      portfolio_id: portfolioId,
+      ...updates,
+    }
     const envelope = await this.callOperation(
-      'Update portfolio',
-      opUpdatePortfolio({
-        path: { graph_id: graphId },
-        body: {
-          ...updates,
-          portfolio_id: portfolioId,
-        } as UpdatePortfolioOperation,
-      })
+      'Update portfolio block',
+      opUpdatePortfolioBlock({ path: { graph_id: graphId }, body })
     )
-    return rawToInvestorPortfolio(envelope.result as unknown as RawPortfolioResponse)
+    return rawToPortfolioBlock(envelope.result as unknown as RawPortfolioBlockResponse)
   }
 
   /**
-   * Delete a portfolio. Fails with 409 if the portfolio still has active
-   * positions — dispose those first.
+   * Cascade-delete the portfolio plus all of its positions. When the
+   * portfolio still has active positions, the request must include
+   * `confirmActivePositions: true` — safety belt to prevent accidental
+   * cascade. Disposed-only portfolios delete without the flag.
    */
-  async deletePortfolio(graphId: string, portfolioId: string): Promise<{ deleted: boolean }> {
+  async deletePortfolioBlock(
+    graphId: string,
+    portfolioId: string,
+    options?: { confirmActivePositions?: boolean }
+  ): Promise<{ deleted: boolean }> {
+    const body: DeletePortfolioBlockOperation = {
+      portfolio_id: portfolioId,
+      confirm_active_positions: options?.confirmActivePositions ?? false,
+    }
     const envelope = await this.callOperation(
-      'Delete portfolio',
-      opDeletePortfolio({
-        path: { graph_id: graphId },
-        body: { portfolio_id: portfolioId },
-      })
+      'Delete portfolio block',
+      opDeletePortfolioBlock({ path: { graph_id: graphId }, body })
     )
     return (envelope.result ?? { deleted: true }) as { deleted: boolean }
   }
@@ -254,7 +291,7 @@ export class InvestorClient {
     return (envelope.result ?? { deleted: true }) as { deleted: boolean }
   }
 
-  // ── Positions ───────────────────────────────────────────────────────
+  // ── Positions (reads only — writes folded into Portfolio Block) ─────
 
   /** List positions with pagination and filters. */
   async listPositions(
@@ -293,46 +330,6 @@ export class InvestorClient {
     )
   }
 
-  /** Create a new position. */
-  async createPosition(graphId: string, body: CreatePositionRequest): Promise<InvestorPosition> {
-    const envelope = await this.callOperation(
-      'Create position',
-      opCreatePosition({ path: { graph_id: graphId }, body })
-    )
-    return rawToInvestorPosition(envelope.result as unknown as RawPositionResponse)
-  }
-
-  /** Update a position. Only provided fields are applied. */
-  async updatePosition(
-    graphId: string,
-    positionId: string,
-    updates: Omit<UpdatePositionOperation, 'position_id'>
-  ): Promise<InvestorPosition> {
-    const envelope = await this.callOperation(
-      'Update position',
-      opUpdatePosition({
-        path: { graph_id: graphId },
-        body: {
-          ...updates,
-          position_id: positionId,
-        } as UpdatePositionOperation,
-      })
-    )
-    return rawToInvestorPosition(envelope.result as unknown as RawPositionResponse)
-  }
-
-  /** Delete (dispose) a position. */
-  async deletePosition(graphId: string, positionId: string): Promise<{ deleted: boolean }> {
-    const envelope = await this.callOperation(
-      'Delete position',
-      opDeletePosition({
-        path: { graph_id: graphId },
-        body: { position_id: positionId },
-      })
-    )
-    return (envelope.result ?? { deleted: true }) as { deleted: boolean }
-  }
-
   // ── Holdings (aggregation) ─────────────────────────────────────────
 
   /**
@@ -390,27 +387,13 @@ export class InvestorClient {
 
 // ── Module-private conversion helpers ─────────────────────────────────
 //
-// The RoboInvestor write operations (create/update portfolio, security,
-// position) return Pydantic-serialized envelopes where `result` is in
-// snake_case. The GraphQL-derived `InvestorPortfolio` / `InvestorSecurity`
-// / `InvestorPosition` types are in camelCase (matching the read path).
-//
-// These helpers are the single place where we bridge the two naming
-// conventions on the write path, mirroring the `rawFiscalCalendarToCamel`
-// / `rawToClosingEntry` pattern in `LedgerClient`. Keeping the unsafe
-// `as unknown as` cast localized to these helpers means a backend schema
-// drift surfaces here rather than silently at every call site.
-
-interface RawPortfolioResponse {
-  id: string
-  name: string
-  description: string | null
-  strategy: string | null
-  inception_date: string | null
-  base_currency: string
-  created_at: string
-  updated_at: string
-}
+// The RoboInvestor write operations return Pydantic-serialized envelopes
+// where `result` is in snake_case. The GraphQL-derived `Investor*` types
+// are in camelCase (matching the read path). These helpers are the single
+// place where we bridge the two naming conventions on the write path,
+// mirroring the equivalent helpers in `LedgerClient`. Keeping the unsafe
+// `as unknown as` cast localized here means a backend schema drift surfaces
+// in one place rather than silently at every call site.
 
 interface RawSecurityResponse {
   id: string
@@ -428,40 +411,50 @@ interface RawSecurityResponse {
   updated_at: string
 }
 
-interface RawPositionResponse {
+interface RawEntityLite {
+  id: string
+  name: string
+  source_graph_id: string | null
+}
+
+interface RawSecurityLite {
+  id: string
+  name: string
+  security_type: string
+  security_subtype: string | null
+  is_active: boolean
+  issuer: RawEntityLite | null
+  source_graph_id: string | null
+}
+
+interface RawPositionBlock {
   id: string
-  portfolio_id: string
-  security_id: string
-  security_name: string | null
-  entity_name: string | null
   quantity: number
   quantity_type: string
-  cost_basis: number
   cost_basis_dollars: number
-  currency: string
-  current_value: number | null
   current_value_dollars: number | null
   valuation_date: string | null
   valuation_source: string | null
   acquisition_date: string | null
-  disposition_date: string | null
   status: string
   notes: string | null
-  created_at: string
-  updated_at: string
+  security: RawSecurityLite
 }
 
-function rawToInvestorPortfolio(raw: RawPortfolioResponse): InvestorPortfolio {
-  return {
-    id: raw.id,
-    name: raw.name,
-    description: raw.description,
-    strategy: raw.strategy,
-    inceptionDate: raw.inception_date,
-    baseCurrency: raw.base_currency,
-    createdAt: raw.created_at,
-    updatedAt: raw.updated_at,
-  }
+interface RawPortfolioBlockResponse {
+  id: string
+  name: string
+  description: string | null
+  strategy: string | null
+  inception_date: string | null
+  base_currency: string
+  owner: RawEntityLite | null
+  positions: RawPositionBlock[]
+  total_cost_basis_dollars: number
+  total_current_value_dollars: number | null
+  active_position_count: number
+  created_at: string
+  updated_at: string
 }
 
 function rawToInvestorSecurity(raw: RawSecurityResponse): InvestorSecurity {
@@ -482,26 +475,56 @@ function rawToInvestorSecurity(raw: RawSecurityResponse): InvestorSecurity {
   }
 }
 
-function rawToInvestorPosition(raw: RawPositionResponse): InvestorPosition {
+function rawToEntityLite(raw: RawEntityLite | null): InvestorEntityLite {
+  if (raw === null) return null
+  return {
+    id: raw.id,
+    name: raw.name,
+    sourceGraphId: raw.source_graph_id,
+  }
+}
+
+function rawToSecurityLite(raw: RawSecurityLite): InvestorSecurityLite {
+  return {
+    id: raw.id,
+    name: raw.name,
+    securityType: raw.security_type,
+    securitySubtype: raw.security_subtype,
+    isActive: raw.is_active,
+    issuer: rawToEntityLite(raw.issuer),
+    sourceGraphId: raw.source_graph_id,
+  }
+}
+
+function rawToPositionBlock(raw: RawPositionBlock): InvestorPositionBlock {
   return {
     id: raw.id,
-    portfolioId: raw.portfolio_id,
-    securityId: raw.security_id,
-    securityName: raw.security_name,
-    entityName: raw.entity_name,
     quantity: raw.quantity,
     quantityType: raw.quantity_type,
-    costBasis: raw.cost_basis,
     costBasisDollars: raw.cost_basis_dollars,
-    currency: raw.currency,
-    currentValue: raw.current_value,
     currentValueDollars: raw.current_value_dollars,
     valuationDate: raw.valuation_date,
     valuationSource: raw.valuation_source,
     acquisitionDate: raw.acquisition_date,
-    dispositionDate: raw.disposition_date,
     status: raw.status,
     notes: raw.notes,
+    security: rawToSecurityLite(raw.security),
+  }
+}
+
+function rawToPortfolioBlock(raw: RawPortfolioBlockResponse): InvestorPortfolioBlock {
+  return {
+    id: raw.id,
+    name: raw.name,
+    description: raw.description,
+    strategy: raw.strategy,
+    inceptionDate: raw.inception_date,
+    baseCurrency: raw.base_currency,
+    owner: rawToEntityLite(raw.owner),
+    positions: raw.positions.map(rawToPositionBlock),
+    totalCostBasisDollars: raw.total_cost_basis_dollars,
+    totalCurrentValueDollars: raw.total_current_value_dollars,
+    activePositionCount: raw.active_position_count,
     createdAt: raw.created_at,
     updatedAt: raw.updated_at,
   }

package/artifacts/LedgerClient.d.ts

@@ -1,6 +1,6 @@
 import type { AutoMapElementsOperation, CreateAgentRequest, CreateEventBlockRequest, CreateEventHandlerRequest, CreateMappingAssociationOperation, CreateTaxonomyBlockRequest, CreateViewRequest, DeleteMappingAssociationOperation, DeleteTaxonomyBlockRequest, EvaluateRulesRequest, FinancialStatementAnalysisRequest, LinkEntityTaxonomyRequest, LiveFinancialStatementRequest, OperationEnvelope, UpdateAgentRequest, UpdateEntityRequest, UpdateEventBlockRequest, UpdateEventHandlerRequest, UpdateJournalEntryRequest, UpdateTaxonomyBlockRequest } from '../types.gen';
 import type { TokenProvider } from './graphql/client';
-import { type GetInformationBlockQuery, type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerPublishListQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerReportQuery, type GetLedgerStatementQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListInformationBlocksQuery, type ListLedgerAccountsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerMappingsQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery } from './graphql/generated/graphql';
+import { type GetInformationBlockQuery, type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, 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 ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerMappingsQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery } from './graphql/generated/graphql';
 export type LedgerEntity = NonNullable<GetLedgerEntityQuery['entity']>;
 export type LedgerEntitySummary = ListLedgerEntitiesQuery['entities'][number];
 export type LedgerSummary = NonNullable<GetLedgerSummaryQuery['summary']>;
@@ -39,6 +39,8 @@ export type LedgerClosingBookStructures = NonNullable<GetLedgerClosingBookStruct
 export type LedgerFiscalCalendar = NonNullable<GetLedgerFiscalCalendarQuery['fiscalCalendar']>;
 export type LedgerFiscalPeriod = LedgerFiscalCalendar['periods'][number];
 export type Report = NonNullable<GetLedgerReportQuery['report']>;
+export type ReportPackage = NonNullable<GetLedgerReportPackageQuery['reportPackage']>;
+export type ReportPackageItem = ReportPackage['items'][number];
 export type ReportListItem = NonNullable<ListLedgerReportsQuery['reports']>['reports'][number];
 export type StatementData = NonNullable<GetLedgerStatementQuery['statement']>;
 export type StatementPeriod = StatementData['periods'][number];
@@ -446,6 +448,13 @@ export declare class LedgerClient {
     listReports(graphId: string): Promise<ReportListItem[]>;
     /** Get a single report with its period list + available structures. */
     getReport(graphId: string, reportId: string): Promise<Report | null>;
+    /**
+     * Rehydrate a Report as a package — Report metadata + N
+     * `InformationBlock` envelopes (one per attached FactSet). Drives the
+     * package viewer; returns everything needed to render BS + IS (and any
+     * other statements the Report generated) without per-section fetches.
+     */
+    getReportPackage(graphId: string, reportId: string): Promise<ReportPackage | null>;
     /**
      * Render a financial statement — facts viewed through a structure.
      *
@@ -464,6 +473,18 @@ export declare class LedgerClient {
      * Each target graph receives a snapshot copy of the report's facts.
      */
     shareReport(graphId: string, reportId: string, publishListId: string): Promise<ReportOperationAck>;
+    /**
+     * Transition a Report's filing_status to 'filed' — locks the package.
+     * Allowed from 'draft' or 'under_review'. Stamps filed_at + filed_by
+     * from the auth context + server clock.
+     */
+    fileReport(graphId: string, reportId: string): Promise<ReportOperationAck>;
+    /**
+     * Move a Report along the non-file legs of the filing lifecycle
+     * (draft ↔ under_review, filed → archived). Use ``fileReport`` to
+     * reach 'filed' so the audit fields land cleanly.
+     */
+    transitionFilingStatus(graphId: string, reportId: string, targetStatus: string): Promise<ReportOperationAck>;
     /** Check if a report was received via sharing (vs locally created). */
     isSharedReport(report: Report): boolean;
     /** List publish lists with pagination. */

package/artifacts/LedgerClient.js

@@ -624,6 +624,15 @@ class LedgerClient {
     async getReport(graphId, reportId) {
         return this.gqlQuery(graphId, graphql_1.GetLedgerReportDocument, { reportId }, 'Get report', (data) => data.report);
     }
+    /**
+     * Rehydrate a Report as a package — Report metadata + N
+     * `InformationBlock` envelopes (one per attached FactSet). Drives the
+     * package viewer; returns everything needed to render BS + IS (and any
+     * other statements the Report generated) without per-section fetches.
+     */
+    async getReportPackage(graphId, reportId) {
+        return this.gqlQuery(graphId, graphql_1.GetLedgerReportPackageDocument, { reportId }, 'Get report package', (data) => data.reportPackage);
+    }
     /**
      * Render a financial statement — facts viewed through a structure.
      *
@@ -676,6 +685,37 @@ class LedgerClient {
             result: envelope.result ?? null,
         };
     }
+    /**
+     * Transition a Report's filing_status to 'filed' — locks the package.
+     * Allowed from 'draft' or 'under_review'. Stamps filed_at + filed_by
+     * from the auth context + server clock.
+     */
+    async fileReport(graphId, reportId) {
+        const body = { report_id: reportId };
+        const envelope = await this.callOperation('File report', (0, sdk_gen_1.opFileReport)({ path: { graph_id: graphId }, body }));
+        return {
+            operationId: envelope.operationId,
+            status: envelope.status,
+            result: envelope.result ?? null,
+        };
+    }
+    /**
+     * Move a Report along the non-file legs of the filing lifecycle
+     * (draft ↔ under_review, filed → archived). Use ``fileReport`` to
+     * reach 'filed' so the audit fields land cleanly.
+     */
+    async transitionFilingStatus(graphId, reportId, targetStatus) {
+        const body = {
+            report_id: reportId,
+            target_status: targetStatus,
+        };
+        const envelope = await this.callOperation('Transition filing status', (0, sdk_gen_1.opTransitionFilingStatus)({ path: { graph_id: graphId }, body }));
+        return {
+            operationId: envelope.operationId,
+            status: envelope.status,
+            result: envelope.result ?? null,
+        };
+    }
     /** Check if a report was received via sharing (vs locally created). */
     isSharedReport(report) {
         return report.sourceGraphId !== null;

package/artifacts/LedgerClient.ts

@@ -44,6 +44,7 @@ import {
   opDeleteReport,
   opDeleteTaxonomyBlock,
   opEvaluateRules,
+  opFileReport,
   opFinancialStatementAnalysis,
   opInitializeLedger,
   opLinkEntityTaxonomy,
@@ -54,6 +55,7 @@ import {
   opReopenPeriod,
   opSetCloseTarget,
   opShareReport,
+  opTransitionFilingStatus,
   opUpdateAgent,
   opUpdateEntity,
   opUpdateEventBlock,
@@ -81,6 +83,7 @@ import type {
   DeleteMappingAssociationOperation,
   DeleteTaxonomyBlockRequest,
   EvaluateRulesRequest,
+  FileReportRequest,
   FinancialStatementAnalysisRequest,
   InitializeLedgerRequest,
   LinkEntityTaxonomyRequest,
@@ -88,6 +91,7 @@ import type {
   OperationEnvelope,
   ReopenPeriodOperation,
   SetCloseTargetOperation,
+  TransitionFilingStatusRequest,
   UpdateAgentRequest,
   UpdateEntityRequest,
   UpdateEventBlockRequest,
@@ -114,6 +118,7 @@ import {
   GetLedgerPublishListDocument,
   GetLedgerReportDocument,
   GetLedgerReportingTaxonomyDocument,
+  GetLedgerReportPackageDocument,
   GetLedgerStatementDocument,
   GetLedgerSummaryDocument,
   GetLedgerTransactionDocument,
@@ -142,6 +147,7 @@ import {
   type GetLedgerPeriodDraftsQuery,
   type GetLedgerPublishListQuery,
   type GetLedgerReportingTaxonomyQuery,
+  type GetLedgerReportPackageQuery,
   type GetLedgerReportQuery,
   type GetLedgerStatementQuery,
   type GetLedgerSummaryQuery,
@@ -227,6 +233,8 @@ export type LedgerFiscalPeriod = LedgerFiscalCalendar['periods'][number]
 
 // Reports + publish lists + statements
 export type Report = NonNullable<GetLedgerReportQuery['report']>
+export type ReportPackage = NonNullable<GetLedgerReportPackageQuery['reportPackage']>
+export type ReportPackageItem = ReportPackage['items'][number]
 export type ReportListItem = NonNullable<ListLedgerReportsQuery['reports']>['reports'][number]
 export type StatementData = NonNullable<GetLedgerStatementQuery['statement']>
 export type StatementPeriod = StatementData['periods'][number]
@@ -1532,6 +1540,22 @@ export class LedgerClient {
     )
   }
 
+  /**
+   * Rehydrate a Report as a package — Report metadata + N
+   * `InformationBlock` envelopes (one per attached FactSet). Drives the
+   * package viewer; returns everything needed to render BS + IS (and any
+   * other statements the Report generated) without per-section fetches.
+   */
+  async getReportPackage(graphId: string, reportId: string): Promise<ReportPackage | null> {
+    return this.gqlQuery(
+      graphId,
+      GetLedgerReportPackageDocument,
+      { reportId },
+      'Get report package',
+      (data) => data.reportPackage
+    )
+  }
+
   /**
    * Render a financial statement — facts viewed through a structure.
    *
@@ -1616,6 +1640,49 @@ export class LedgerClient {
     }
   }
 
+  /**
+   * Transition a Report's filing_status to 'filed' — locks the package.
+   * Allowed from 'draft' or 'under_review'. Stamps filed_at + filed_by
+   * from the auth context + server clock.
+   */
+  async fileReport(graphId: string, reportId: string): Promise<ReportOperationAck> {
+    const body: FileReportRequest = { report_id: reportId }
+    const envelope = await this.callOperation(
+      'File report',
+      opFileReport({ path: { graph_id: graphId }, body })
+    )
+    return {
+      operationId: envelope.operationId,
+      status: envelope.status,
+      result: (envelope.result as Record<string, unknown> | null) ?? null,
+    }
+  }
+
+  /**
+   * Move a Report along the non-file legs of the filing lifecycle
+   * (draft ↔ under_review, filed → archived). Use ``fileReport`` to
+   * reach 'filed' so the audit fields land cleanly.
+   */
+  async transitionFilingStatus(
+    graphId: string,
+    reportId: string,
+    targetStatus: string
+  ): Promise<ReportOperationAck> {
+    const body: TransitionFilingStatusRequest = {
+      report_id: reportId,
+      target_status: targetStatus,
+    }
+    const envelope = await this.callOperation(
+      'Transition filing status',
+      opTransitionFilingStatus({ path: { graph_id: graphId }, 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