@robosystems/client 0.2.38 → 0.2.40

package/extensions/LedgerClient.d.ts

@@ -0,0 +1,139 @@
+import type { AccountListResponse, AccountTreeResponse, LedgerSummaryResponse, LedgerTransactionDetailResponse, LedgerTransactionListResponse, MappingDetailResponse, TrialBalanceResponse } from '../types.gen';
+export interface LedgerEntity {
+    id: string;
+    name: string;
+    legalName: string | null;
+    entityType: string | null;
+    industry: string | null;
+    status: string | null;
+}
+export interface MappingInfo {
+    id: string;
+    name: string;
+    description: string | null;
+    structureType: string;
+    taxonomyId: string;
+    isActive: boolean;
+}
+export interface MappingCoverage {
+    totalCoaElements: number;
+    mappedCount: number;
+    unmappedCount: number;
+    coveragePercent: number;
+    highConfidence: number;
+    mediumConfidence: number;
+    lowConfidence: number;
+}
+export interface Structure {
+    id: string;
+    name: string;
+    structureType: string;
+}
+export declare class LedgerClient {
+    private config;
+    constructor(config: {
+        baseUrl: string;
+        credentials?: 'include' | 'same-origin' | 'omit';
+        headers?: Record<string, string>;
+        token?: string;
+    });
+    /**
+     * Get the entity (company/organization) for this graph.
+     */
+    getEntity(graphId: string): Promise<LedgerEntity | null>;
+    /**
+     * List accounts (flat).
+     */
+    listAccounts(graphId: string): Promise<AccountListResponse>;
+    /**
+     * Get the account tree (hierarchical).
+     */
+    getAccountTree(graphId: string): Promise<AccountTreeResponse>;
+    /**
+     * List transactions with optional date filters.
+     */
+    listTransactions(graphId: string, options?: {
+        startDate?: string;
+        endDate?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<LedgerTransactionListResponse>;
+    /**
+     * Get transaction detail with entries and line items.
+     */
+    getTransaction(graphId: string, transactionId: string): Promise<LedgerTransactionDetailResponse>;
+    /**
+     * Get trial balance (CoA-level debits/credits).
+     */
+    getTrialBalance(graphId: string, options?: {
+        startDate?: string;
+        endDate?: string;
+    }): Promise<TrialBalanceResponse>;
+    /**
+     * Get mapped trial balance (CoA rolled up to GAAP concepts).
+     */
+    getMappedTrialBalance(graphId: string, options?: {
+        mappingId?: string;
+        startDate?: string;
+        endDate?: string;
+    }): Promise<unknown>;
+    /**
+     * Get ledger summary (account count, transaction count, date range).
+     */
+    getSummary(graphId: string): Promise<LedgerSummaryResponse>;
+    /**
+     * Get the reporting taxonomy (US GAAP seed).
+     */
+    getReportingTaxonomy(graphId: string): Promise<unknown>;
+    /**
+     * List reporting structures (IS, BS, CF) for a taxonomy.
+     */
+    listStructures(graphId: string, taxonomyId?: string): Promise<Structure[]>;
+    /**
+     * List elements (CoA accounts, GAAP concepts, etc.).
+     */
+    listElements(graphId: string, options?: {
+        taxonomyId?: string;
+        source?: string;
+        classification?: string;
+        isAbstract?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    /**
+     * Create a new CoA→GAAP mapping structure.
+     * Returns the created mapping info.
+     */
+    createMappingStructure(graphId: string, options?: {
+        name?: string;
+        description?: string;
+        taxonomyId?: string;
+    }): Promise<MappingInfo>;
+    /**
+     * List available CoA→GAAP mapping structures.
+     */
+    listMappings(graphId: string): Promise<MappingInfo[]>;
+    /**
+     * Get mapping detail — all associations with element names.
+     */
+    getMappingDetail(graphId: string, mappingId: string): Promise<MappingDetailResponse>;
+    /**
+     * Get mapping coverage — how many CoA elements are mapped.
+     */
+    getMappingCoverage(graphId: string, mappingId: string): Promise<MappingCoverage>;
+    /**
+     * Create a manual mapping association (CoA element → GAAP element).
+     */
+    createMapping(graphId: string, mappingId: string, fromElementId: string, toElementId: string, confidence?: number): Promise<void>;
+    /**
+     * Delete a mapping association.
+     */
+    deleteMapping(graphId: string, mappingId: string, associationId: string): Promise<void>;
+    /**
+     * Trigger AI auto-mapping (MappingAgent).
+     * Returns immediately — the agent runs in the background.
+     */
+    autoMap(graphId: string, mappingId: string): Promise<{
+        operationId?: string;
+    }>;
+}

package/extensions/LedgerClient.js

@@ -0,0 +1,320 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LedgerClient = void 0;
+/**
+ * Ledger Client for RoboSystems API
+ *
+ * High-level client for all ledger concerns: chart of accounts, transactions,
+ * trial balance, taxonomy, mappings, and AI auto-mapping. This is the
+ * operational backbone — reports consume these as inputs.
+ */
+const sdk_gen_1 = require("../sdk.gen");
+// ── Client ──────────────────────────────────────────────────────────────
+class LedgerClient {
+    constructor(config) {
+        this.config = config;
+    }
+    // ── Entity ──────────────────────────────────────────────────────────
+    /**
+     * Get the entity (company/organization) for this graph.
+     */
+    async getEntity(graphId) {
+        const response = await (0, sdk_gen_1.getLedgerEntity)({
+            path: { graph_id: graphId },
+        });
+        if (response.response.status === 404)
+            return null;
+        if (response.error) {
+            throw new Error(`Get entity failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            id: data.id,
+            name: data.name,
+            legalName: data.legal_name ?? null,
+            entityType: data.entity_type ?? null,
+            industry: data.industry ?? null,
+            status: data.status ?? null,
+        };
+    }
+    // ── Accounts (Chart of Accounts) ───────────────────────────────────
+    /**
+     * List accounts (flat).
+     */
+    async listAccounts(graphId) {
+        const response = await (0, sdk_gen_1.listLedgerAccounts)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`List accounts failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    /**
+     * Get the account tree (hierarchical).
+     */
+    async getAccountTree(graphId) {
+        const response = await (0, sdk_gen_1.getLedgerAccountTree)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`Get account tree failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    // ── Transactions ────────────────────────────────────────────────────
+    /**
+     * List transactions with optional date filters.
+     */
+    async listTransactions(graphId, options) {
+        const response = await (0, sdk_gen_1.listLedgerTransactions)({
+            path: { graph_id: graphId },
+            query: {
+                start_date: options?.startDate,
+                end_date: options?.endDate,
+                limit: options?.limit,
+                offset: options?.offset,
+            },
+        });
+        if (response.error) {
+            throw new Error(`List transactions failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    /**
+     * Get transaction detail with entries and line items.
+     */
+    async getTransaction(graphId, transactionId) {
+        const response = await (0, sdk_gen_1.getLedgerTransaction)({
+            path: { graph_id: graphId, transaction_id: transactionId },
+        });
+        if (response.error) {
+            throw new Error(`Get transaction failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    // ── Trial Balance ──────────────────────────────────────────────────
+    /**
+     * Get trial balance (CoA-level debits/credits).
+     */
+    async getTrialBalance(graphId, options) {
+        const response = await (0, sdk_gen_1.getLedgerTrialBalance)({
+            path: { graph_id: graphId },
+            query: {
+                start_date: options?.startDate,
+                end_date: options?.endDate,
+            },
+        });
+        if (response.error) {
+            throw new Error(`Get trial balance failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    /**
+     * Get mapped trial balance (CoA rolled up to GAAP concepts).
+     */
+    async getMappedTrialBalance(graphId, options) {
+        const response = await (0, sdk_gen_1.getMappedTrialBalance)({
+            path: { graph_id: graphId },
+            query: {
+                mapping_id: options?.mappingId,
+                start_date: options?.startDate,
+                end_date: options?.endDate,
+            },
+        });
+        if (response.error) {
+            throw new Error(`Get mapped trial balance failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    // ── Summary ────────────────────────────────────────────────────────
+    /**
+     * Get ledger summary (account count, transaction count, date range).
+     */
+    async getSummary(graphId) {
+        const response = await (0, sdk_gen_1.getLedgerSummary)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`Get summary failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    // ── Taxonomy ────────────────────────────────────────────────────────
+    /**
+     * Get the reporting taxonomy (US GAAP seed).
+     */
+    async getReportingTaxonomy(graphId) {
+        const response = await (0, sdk_gen_1.getReportingTaxonomy)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`Get reporting taxonomy failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    /**
+     * List reporting structures (IS, BS, CF) for a taxonomy.
+     */
+    async listStructures(graphId, taxonomyId) {
+        const response = await (0, sdk_gen_1.listStructures)({
+            path: { graph_id: graphId },
+            query: taxonomyId ? { taxonomy_id: taxonomyId } : undefined,
+        });
+        if (response.error) {
+            throw new Error(`List structures failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return (data.structures ?? []).map((s) => ({
+            id: s.id,
+            name: s.name,
+            structureType: s.structure_type,
+        }));
+    }
+    /**
+     * List elements (CoA accounts, GAAP concepts, etc.).
+     */
+    async listElements(graphId, options) {
+        const response = await (0, sdk_gen_1.listElements)({
+            path: { graph_id: graphId },
+            query: {
+                taxonomy_id: options?.taxonomyId,
+                source: options?.source,
+                classification: options?.classification,
+                is_abstract: options?.isAbstract,
+                limit: options?.limit,
+                offset: options?.offset,
+            },
+        });
+        if (response.error) {
+            throw new Error(`List elements failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    // ── Mappings ────────────────────────────────────────────────────────
+    /**
+     * Create a new CoA→GAAP mapping structure.
+     * Returns the created mapping info.
+     */
+    async createMappingStructure(graphId, options) {
+        const response = await (0, sdk_gen_1.createStructure)({
+            path: { graph_id: graphId },
+            body: {
+                name: options?.name ?? 'CoA to Reporting',
+                description: options?.description ?? 'Map Chart of Accounts to US GAAP reporting concepts',
+                structure_type: 'coa_mapping',
+                taxonomy_id: options?.taxonomyId ?? 'tax_usgaap_reporting',
+            },
+        });
+        if (response.error) {
+            throw new Error(`Create mapping structure failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            id: data.id,
+            name: data.name,
+            description: data.description ?? null,
+            structureType: data.structure_type,
+            taxonomyId: data.taxonomy_id,
+            isActive: data.is_active ?? true,
+        };
+    }
+    /**
+     * List available CoA→GAAP mapping structures.
+     */
+    async listMappings(graphId) {
+        const response = await (0, sdk_gen_1.listMappings)({
+            path: { graph_id: graphId },
+        });
+        if (response.error) {
+            throw new Error(`List mappings failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return (data.structures ?? []).map((s) => ({
+            id: s.id,
+            name: s.name,
+            description: s.description ?? null,
+            structureType: s.structure_type,
+            taxonomyId: s.taxonomy_id,
+            isActive: s.is_active ?? true,
+        }));
+    }
+    /**
+     * Get mapping detail — all associations with element names.
+     */
+    async getMappingDetail(graphId, mappingId) {
+        const response = await (0, sdk_gen_1.getMappingDetail)({
+            path: { graph_id: graphId, mapping_id: mappingId },
+        });
+        if (response.error) {
+            throw new Error(`Get mapping detail failed: ${JSON.stringify(response.error)}`);
+        }
+        return response.data;
+    }
+    /**
+     * Get mapping coverage — how many CoA elements are mapped.
+     */
+    async getMappingCoverage(graphId, mappingId) {
+        const response = await (0, sdk_gen_1.getMappingCoverage)({
+            path: { graph_id: graphId, mapping_id: mappingId },
+        });
+        if (response.error) {
+            throw new Error(`Get mapping coverage failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            totalCoaElements: data.total_coa_elements ?? 0,
+            mappedCount: data.mapped_count ?? 0,
+            unmappedCount: data.unmapped_count ?? 0,
+            coveragePercent: data.coverage_percent ?? 0,
+            highConfidence: data.high_confidence ?? 0,
+            mediumConfidence: data.medium_confidence ?? 0,
+            lowConfidence: data.low_confidence ?? 0,
+        };
+    }
+    /**
+     * Create a manual mapping association (CoA element → GAAP element).
+     */
+    async createMapping(graphId, mappingId, fromElementId, toElementId, confidence) {
+        const response = await (0, sdk_gen_1.createMappingAssociation)({
+            path: { graph_id: graphId, mapping_id: mappingId },
+            body: {
+                from_element_id: fromElementId,
+                to_element_id: toElementId,
+                confidence: confidence ?? 1.0,
+            },
+        });
+        if (response.error) {
+            throw new Error(`Create mapping failed: ${JSON.stringify(response.error)}`);
+        }
+    }
+    /**
+     * Delete a mapping association.
+     */
+    async deleteMapping(graphId, mappingId, associationId) {
+        const response = await (0, sdk_gen_1.deleteMappingAssociation)({
+            path: { graph_id: graphId, mapping_id: mappingId, association_id: associationId },
+        });
+        if (response.error) {
+            throw new Error(`Delete mapping failed: ${JSON.stringify(response.error)}`);
+        }
+    }
+    /**
+     * Trigger AI auto-mapping (MappingAgent).
+     * Returns immediately — the agent runs in the background.
+     */
+    async autoMap(graphId, mappingId) {
+        const response = await (0, sdk_gen_1.autoMapElements)({
+            path: { graph_id: graphId, mapping_id: mappingId },
+        });
+        if (response.error) {
+            throw new Error(`Auto-map failed: ${JSON.stringify(response.error)}`);
+        }
+        const data = response.data;
+        return {
+            operationId: data?.operation_id,
+        };
+    }
+}
+exports.LedgerClient = LedgerClient;