sec-edgar-api 1.0.0 → 1.0.1

package/build/examples/xbrl-practical-examples.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Practical examples of working with XBRL relationships using your existing types
+ */
+import type { XbrlInstance, XbrlLinkbase } from '../types';
+/**
+ * Example 1: Extract presentation hierarchy from your XBRL data
+ */
+export declare function extractPresentationHierarchy(presentationLinkbase: XbrlLinkbase): Record<string, ConceptNode>;
+/**
+ * Example 2: Extract calculation relationships
+ */
+export declare function extractCalculationRelationships(calculationLinkbase: XbrlLinkbase): Record<string, CalculationRule>;
+/**
+ * Example 3: Extract dimensional relationships (axis/member mappings)
+ */
+export declare function extractDimensionalRelationships(definitionLinkbase: XbrlLinkbase): Record<string, DimensionStructure>;
+/**
+ * Example 4: Find facts with specific dimensional context
+ */
+export declare function findFactsWithDimensions(instance: XbrlInstance, conceptName: string, dimensionFilters?: {
+    dimension: string;
+    member?: string;
+}[]): {
+    fact: import("../types").XbrlElement;
+    context: import("../types").XbrlContext;
+    dimensions: {
+        dimension: string;
+        member: string;
+    }[];
+}[];
+/**
+ * Example 5: Build a complete concept map with all relationships
+ */
+export declare function buildCompleteConceptMap(linkbases: {
+    presentation: XbrlLinkbase;
+    calculation: XbrlLinkbase;
+    definition: XbrlLinkbase;
+    label: XbrlLinkbase;
+}): Map<string, CompleteConcept>;
+interface ConceptNode {
+    concept: string;
+    children: ConceptChild[];
+    role: string;
+    order: number;
+}
+interface ConceptChild {
+    concept: string;
+    order: number;
+    preferredLabel?: string;
+}
+interface CalculationRule {
+    summationItem: string;
+    contributingItems: CalculationItem[];
+}
+interface CalculationItem {
+    concept: string;
+    weight: number;
+    order: number;
+}
+interface DimensionStructure {
+    concept: string;
+    type: string;
+    dimensions?: string[];
+    domains?: string[];
+    members?: string[];
+}
+interface ConceptLabel {
+    text: string;
+    role: string;
+    lang: string;
+}
+interface CompleteConcept {
+    name: string;
+    labels: ConceptLabel[];
+    presentation: ConceptNode | null;
+    calculation: CalculationRule | null;
+    dimensions: DimensionStructure | null;
+}
+export declare function usageExamples(): {
+    segmentRevenue: {
+        fact: import("../types").XbrlElement;
+        context: import("../types").XbrlContext;
+        dimensions: {
+            dimension: string;
+            member: string;
+        }[];
+    }[];
+    northAmericaRevenue: {
+        fact: import("../types").XbrlElement;
+        context: import("../types").XbrlContext;
+        dimensions: {
+            dimension: string;
+            member: string;
+        }[];
+    }[];
+};
+export {};

package/build/examples/xbrl-practical-examples.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * Practical examples of working with XBRL relationships using your existing types
+ */
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usageExamples = exports.buildCompleteConceptMap = exports.findFactsWithDimensions = exports.extractDimensionalRelationships = exports.extractCalculationRelationships = exports.extractPresentationHierarchy = void 0;
+/**
+ * Example 1: Extract presentation hierarchy from your XBRL data
+ */
+function extractPresentationHierarchy(presentationLinkbase) {
+    var _a;
+    var hierarchy = {};
+    // Process each presentation link (usually one per role/statement)
+    (_a = presentationLinkbase.presentationLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var roleUri = link.role || 'default';
+        // Get all concept locators and relationship arcs
+        var locators = (link.loc || []);
+        var arcs = (link.presentationArc || []);
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Build parent-child relationships
+        arcs.forEach(function (arc) {
+            var parent = conceptMap.get(arc.from);
+            var child = conceptMap.get(arc.to);
+            if (parent && child) {
+                // Initialize parent node if it doesn't exist
+                if (!hierarchy[parent]) {
+                    hierarchy[parent] = {
+                        concept: parent,
+                        children: [],
+                        role: roleUri,
+                        order: 0,
+                    };
+                }
+                // Add child with ordering information
+                hierarchy[parent].children.push({
+                    concept: child,
+                    order: arc.order || 0,
+                    preferredLabel: arc.preferredLabel,
+                });
+                // Sort children by order
+                hierarchy[parent].children.sort(function (a, b) { return a.order - b.order; });
+            }
+        });
+    });
+    return hierarchy;
+}
+exports.extractPresentationHierarchy = extractPresentationHierarchy;
+/**
+ * Example 2: Extract calculation relationships
+ */
+function extractCalculationRelationships(calculationLinkbase) {
+    var _a;
+    var calculations = {};
+    (_a = calculationLinkbase.calculationLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var locators = (link.loc || []);
+        var arcs = (link.calculationArc || []);
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Group arcs by summation item (the 'to' end of the arc)
+        var summationGroups = new Map();
+        arcs.forEach(function (arc) {
+            var summationConcept = conceptMap.get(arc.to);
+            if (summationConcept) {
+                if (!summationGroups.has(summationConcept)) {
+                    summationGroups.set(summationConcept, []);
+                }
+                summationGroups.get(summationConcept).push(arc);
+            }
+        });
+        // Build calculation rules
+        summationGroups.forEach(function (contributingArcs, summationConcept) {
+            calculations[summationConcept] = {
+                summationItem: summationConcept,
+                contributingItems: contributingArcs.map(function (arc) { return ({
+                    concept: conceptMap.get(arc.from) || '',
+                    weight: arc.weight || 1,
+                    order: arc.order || 0,
+                }); }),
+            };
+        });
+    });
+    return calculations;
+}
+exports.extractCalculationRelationships = extractCalculationRelationships;
+/**
+ * Example 3: Extract dimensional relationships (axis/member mappings)
+ */
+function extractDimensionalRelationships(definitionLinkbase) {
+    var _a;
+    var dimensions = {};
+    (_a = definitionLinkbase.definitionLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var locators = (link.loc || []);
+        var arcs = (link.definitionArc || []);
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Process dimensional arcs based on their arcrole
+        arcs.forEach(function (arc) {
+            var fromConcept = conceptMap.get(arc.from);
+            var toConcept = conceptMap.get(arc.to);
+            var arcrole = arc.arcrole || '';
+            if (fromConcept && toConcept) {
+                switch (arcrole) {
+                    case 'http://xbrl.org/int/dim/arcrole/hypercube-dimension':
+                        // Hypercube contains dimension
+                        initializeDimension(dimensions, fromConcept, 'hypercube');
+                        dimensions[fromConcept].dimensions = dimensions[fromConcept].dimensions || [];
+                        dimensions[fromConcept].dimensions.push(toConcept);
+                        break;
+                    case 'http://xbrl.org/int/dim/arcrole/dimension-domain':
+                        // Dimension has domain
+                        initializeDimension(dimensions, fromConcept, 'dimension');
+                        dimensions[fromConcept].domains = dimensions[fromConcept].domains || [];
+                        dimensions[fromConcept].domains.push(toConcept);
+                        break;
+                    case 'http://xbrl.org/int/dim/arcrole/domain-member':
+                        // Domain has member
+                        initializeDimension(dimensions, fromConcept, 'domain');
+                        dimensions[fromConcept].members = dimensions[fromConcept].members || [];
+                        dimensions[fromConcept].members.push(toConcept);
+                        break;
+                }
+            }
+        });
+    });
+    return dimensions;
+}
+exports.extractDimensionalRelationships = extractDimensionalRelationships;
+/**
+ * Example 4: Find facts with specific dimensional context
+ */
+function findFactsWithDimensions(instance, conceptName, dimensionFilters) {
+    var matchingFacts = [];
+    // Filter facts by concept name
+    var conceptFacts = instance.factElements.filter(function (fact) { return fact.name === conceptName; });
+    var _loop_1 = function (fact) {
+        // Get the context for this fact
+        var context = instance.contexts.find(function (ctx) { return ctx.id === fact.contextRef; });
+        if (!context)
+            return "continue";
+        // Check if this fact matches our dimensional filters
+        if (dimensionFilters) {
+            var matchesFilters = dimensionFilters.every(function (filter) {
+                var matchingSegment = context.entity.segment.find(function (seg) { return seg.dimension === filter.dimension; });
+                if (!matchingSegment)
+                    return false;
+                // If specific member is required, check for it
+                if (filter.member && matchingSegment.value !== filter.member) {
+                    return false;
+                }
+                return true;
+            });
+            if (!matchesFilters)
+                return "continue";
+        }
+        matchingFacts.push({
+            fact: fact,
+            context: context,
+            dimensions: context.entity.segment.map(function (seg) { return ({
+                dimension: seg.dimension,
+                member: seg.value,
+            }); }),
+        });
+    };
+    for (var _i = 0, conceptFacts_1 = conceptFacts; _i < conceptFacts_1.length; _i++) {
+        var fact = conceptFacts_1[_i];
+        _loop_1(fact);
+    }
+    return matchingFacts;
+}
+exports.findFactsWithDimensions = findFactsWithDimensions;
+/**
+ * Example 5: Build a complete concept map with all relationships
+ */
+function buildCompleteConceptMap(linkbases) {
+    var conceptMap = new Map();
+    // Extract all relationships
+    var presentationHierarchy = extractPresentationHierarchy(linkbases.presentation);
+    var calculationRelationships = extractCalculationRelationships(linkbases.calculation);
+    var dimensionalRelationships = extractDimensionalRelationships(linkbases.definition);
+    var labels = extractLabels(linkbases.label);
+    // Combine all concepts
+    var allConcepts = new Set(__spreadArray(__spreadArray(__spreadArray(__spreadArray([], Object.keys(presentationHierarchy), true), Object.keys(calculationRelationships), true), Object.keys(dimensionalRelationships), true), Object.keys(labels), true));
+    // Build complete concept entries
+    allConcepts.forEach(function (concept) {
+        conceptMap.set(concept, {
+            name: concept,
+            labels: labels[concept] || [],
+            presentation: presentationHierarchy[concept] || null,
+            calculation: calculationRelationships[concept] || null,
+            dimensions: dimensionalRelationships[concept] || null,
+        });
+    });
+    return conceptMap;
+}
+exports.buildCompleteConceptMap = buildCompleteConceptMap;
+// Helper functions and types
+function extractConceptFromHref(href) {
+    var match = href.match(/#(.+)$/);
+    return match ? match[1] : '';
+}
+function initializeDimension(dimensions, concept, type) {
+    if (!dimensions[concept]) {
+        dimensions[concept] = {
+            concept: concept,
+            type: type,
+            dimensions: [],
+            domains: [],
+            members: [],
+        };
+    }
+}
+function extractLabels(labelLinkbase) {
+    var _a;
+    var labels = {};
+    (_a = labelLinkbase.labelLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var locators = (link.loc || []);
+        var arcs = (link.labelArc || []);
+        var labelResources = link.label || [];
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Connect labels to concepts
+        arcs.forEach(function (arc) {
+            var concept = conceptMap.get(arc.from);
+            var labelResource = labelResources.find(function (r) { return r.label === arc.to; });
+            if (concept && labelResource) {
+                labels[concept] = labels[concept] || [];
+                labels[concept].push({
+                    text: labelResource.text || '',
+                    role: labelResource.role || '',
+                    lang: labelResource.lang || 'en',
+                });
+            }
+        });
+    });
+    return labels;
+}
+// Usage examples:
+function usageExamples() {
+    // Example: Get all revenue facts broken down by segment
+    var segmentRevenue = findFactsWithDimensions({}, // Your XBRL instance
+    'us-gaap:Revenues', [{ dimension: 'us-gaap:SegmentDomain' }]);
+    // Example: Get specific segment revenue
+    var northAmericaRevenue = findFactsWithDimensions({}, 'us-gaap:Revenues', [
+        {
+            dimension: 'us-gaap:SegmentDomain',
+            member: 'us-gaap:NorthAmericaSegmentMember',
+        },
+    ]);
+    return { segmentRevenue: segmentRevenue, northAmericaRevenue: northAmericaRevenue };
+}
+exports.usageExamples = usageExamples;

package/build/examples/xbrl-relationships.d.ts

@@ -0,0 +1,145 @@
+import type { XbrlInstance, XbrlLinkbase, XbrlSchema } from '../types';
+export declare class XbrlRelationshipBuilder {
+    private instance;
+    private schema;
+    private presentationLinkbase;
+    private calculationLinkbase;
+    private definitionLinkbase;
+    private labelLinkbase;
+    constructor(data: {
+        instance: XbrlInstance;
+        schema: XbrlSchema;
+        presentationLinkbase: XbrlLinkbase;
+        calculationLinkbase: XbrlLinkbase;
+        definitionLinkbase: XbrlLinkbase;
+        labelLinkbase: XbrlLinkbase;
+    });
+    /**
+     * 1. PRESENTATION LINKBASE - Defines hierarchical structure
+     * Shows how concepts are organized in financial statements
+     */
+    buildPresentationHierarchy(): Record<string, ConceptHierarchy>;
+    /**
+     * 2. CALCULATION LINKBASE - Defines mathematical relationships
+     * Shows how concepts add up to totals
+     */
+    buildCalculationRelationships(): Record<string, CalculationRelationship>;
+    /**
+     * 3. DEFINITION LINKBASE - Defines dimensional relationships
+     * Shows axis, members, domains, and hypercubes
+     */
+    buildDimensionalRelationships(): Record<string, DimensionalRelationship>;
+    /**
+     * 4. LABEL LINKBASE - Provides human-readable labels
+     * Maps concepts to their display labels
+     */
+    buildLabelMappings(): Record<string, ConceptLabel[]>;
+    /**
+     * 5. RELATING FACTS TO DIMENSIONS
+     * Shows how actual data values relate to dimensional context
+     */
+    buildFactDimensionalMappings(): FactDimensionalMapping[];
+    /**
+     * 6. COMPREHENSIVE TAXONOMY MAPPING
+     * Combines all relationships into a unified structure
+     */
+    buildComprehensiveTaxonomyMap(): {
+        presentation: Record<string, ConceptHierarchy>;
+        calculations: Record<string, CalculationRelationship>;
+        dimensions: Record<string, DimensionalRelationship>;
+        labels: Record<string, ConceptLabel[]>;
+        factMappings: FactDimensionalMapping[];
+        getConceptChildren: (concept: string) => ConceptChild[];
+        getConceptCalculation: (concept: string) => CalculationRelationship;
+        getConceptLabels: (concept: string) => ConceptLabel[];
+        getFactsForConcept: (concept: string) => FactDimensionalMapping[];
+        getDimensionsForConcept: (concept: string) => DimensionalRelationship;
+    };
+    private getLocators;
+    private getPresentationArcs;
+    private getCalculationArcs;
+    private getDefinitionArcs;
+    private getLabelArcs;
+    private getLabelResources;
+    private getConceptFromLocator;
+    private addHypercubeDimension;
+    private addDimensionDomain;
+    private addDomainMember;
+    private addAllRelationship;
+}
+interface ConceptHierarchy {
+    concept: string;
+    children: ConceptChild[];
+    order: number;
+    role: string;
+}
+interface ConceptChild {
+    concept: string;
+    order: number;
+    preferredLabel?: string;
+}
+interface CalculationRelationship {
+    summationItem: string;
+    contributingItems: CalculationItem[];
+}
+interface CalculationItem {
+    concept: string;
+    weight: number;
+    order: number;
+}
+interface DimensionalRelationship {
+    type: 'hypercube' | 'dimension' | 'domain' | 'member';
+    concept: string;
+    dimensions?: DimensionalItem[];
+    domains?: DimensionalItem[];
+    members?: DimensionalItem[];
+    all?: DimensionalItem[];
+}
+interface DimensionalItem {
+    concept: string;
+    type: string;
+}
+interface ConceptLabel {
+    text: string;
+    role: string;
+    lang: string;
+}
+interface FactDimensionalMapping {
+    factName: string;
+    value: string;
+    unit: string;
+    context: DimensionalContext;
+    contextRef: string;
+}
+interface DimensionalContext {
+    entity: string;
+    period: {
+        startDate?: string;
+        endDate?: string;
+        instant?: string;
+    };
+    dimensions: {
+        dimension: string;
+        member: string;
+    }[];
+}
+export declare function exampleUsage(xbrlData: {
+    instance: XbrlInstance;
+    schema: XbrlSchema;
+    presentationLinkbase: XbrlLinkbase;
+    calculationLinkbase: XbrlLinkbase;
+    definitionLinkbase: XbrlLinkbase;
+    labelLinkbase: XbrlLinkbase;
+}): {
+    presentation: Record<string, ConceptHierarchy>;
+    calculations: Record<string, CalculationRelationship>;
+    dimensions: Record<string, DimensionalRelationship>;
+    labels: Record<string, ConceptLabel[]>;
+    factMappings: FactDimensionalMapping[];
+    getConceptChildren: (concept: string) => ConceptChild[];
+    getConceptCalculation: (concept: string) => CalculationRelationship;
+    getConceptLabels: (concept: string) => ConceptLabel[];
+    getFactsForConcept: (concept: string) => FactDimensionalMapping[];
+    getDimensionsForConcept: (concept: string) => DimensionalRelationship;
+};
+export {};

package/build/examples/xbrl-relationships.js

@@ -0,0 +1,337 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exampleUsage = exports.XbrlRelationshipBuilder = void 0;
+/**
+ * Example of how to use XBRL types to relate taxonomies, axis, members, and facts
+ * using linkbases (calculation, presentation, definition, etc.)
+ */
+var fs = require("fs");
+var __1 = require("..");
+// Example: Building a comprehensive XBRL relationship map
+var XbrlRelationshipBuilder = /** @class */ (function () {
+    function XbrlRelationshipBuilder(data) {
+        this.instance = data.instance;
+        this.schema = data.schema;
+        this.presentationLinkbase = data.presentationLinkbase;
+        this.calculationLinkbase = data.calculationLinkbase;
+        this.definitionLinkbase = data.definitionLinkbase;
+        this.labelLinkbase = data.labelLinkbase;
+    }
+    /**
+     * 1. PRESENTATION LINKBASE - Defines hierarchical structure
+     * Shows how concepts are organized in financial statements
+     */
+    XbrlRelationshipBuilder.prototype.buildPresentationHierarchy = function () {
+        var _this = this;
+        var _a;
+        var hierarchy = {};
+        // Process presentation links
+        (_a = this.presentationLinkbase.presentationLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+            var roleUri = link.role || '';
+            // Get locators (concept references)
+            var locators = _this.getLocators(link);
+            var arcs = _this.getPresentationArcs(link);
+            // Build parent-child relationships
+            arcs.forEach(function (arc) {
+                var parentConcept = _this.getConceptFromLocator(locators, arc.from);
+                var childConcept = _this.getConceptFromLocator(locators, arc.to);
+                if (parentConcept && childConcept) {
+                    hierarchy[parentConcept] = hierarchy[parentConcept] || {
+                        concept: parentConcept,
+                        children: [],
+                        order: arc.order || 0,
+                        role: roleUri,
+                    };
+                    hierarchy[parentConcept].children.push({
+                        concept: childConcept,
+                        order: arc.order || 0,
+                        preferredLabel: arc.preferredLabel,
+                    });
+                }
+            });
+        });
+        return hierarchy;
+    };
+    /**
+     * 2. CALCULATION LINKBASE - Defines mathematical relationships
+     * Shows how concepts add up to totals
+     */
+    XbrlRelationshipBuilder.prototype.buildCalculationRelationships = function () {
+        var _this = this;
+        var _a;
+        var calculations = {};
+        (_a = this.calculationLinkbase.calculationLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+            var locators = _this.getLocators(link);
+            var arcs = _this.getCalculationArcs(link);
+            arcs.forEach(function (arc) {
+                var summationConcept = _this.getConceptFromLocator(locators, arc.to);
+                var itemConcept = _this.getConceptFromLocator(locators, arc.from);
+                if (summationConcept && itemConcept) {
+                    calculations[summationConcept] = calculations[summationConcept] || {
+                        summationItem: summationConcept,
+                        contributingItems: [],
+                    };
+                    calculations[summationConcept].contributingItems.push({
+                        concept: itemConcept,
+                        weight: arc.weight || 1,
+                        order: arc.order || 0,
+                    });
+                }
+            });
+        });
+        return calculations;
+    };
+    /**
+     * 3. DEFINITION LINKBASE - Defines dimensional relationships
+     * Shows axis, members, domains, and hypercubes
+     */
+    XbrlRelationshipBuilder.prototype.buildDimensionalRelationships = function () {
+        var _this = this;
+        var _a;
+        var dimensions = {};
+        (_a = this.definitionLinkbase.definitionLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+            var locators = _this.getLocators(link);
+            var arcs = _this.getDefinitionArcs(link);
+            arcs.forEach(function (arc) {
+                var arcrole = arc.arcrole || '';
+                var fromConcept = _this.getConceptFromLocator(locators, arc.from);
+                var toConcept = _this.getConceptFromLocator(locators, arc.to);
+                if (fromConcept && toConcept) {
+                    // Different arcroles define different relationship types
+                    switch (arcrole) {
+                        case 'http://xbrl.org/int/dim/arcrole/hypercube-dimension':
+                            // Hypercube to dimension relationship
+                            _this.addHypercubeDimension(dimensions, fromConcept, toConcept);
+                            break;
+                        case 'http://xbrl.org/int/dim/arcrole/dimension-domain':
+                            // Dimension to domain relationship
+                            _this.addDimensionDomain(dimensions, fromConcept, toConcept);
+                            break;
+                        case 'http://xbrl.org/int/dim/arcrole/domain-member':
+                            // Domain to member relationship
+                            _this.addDomainMember(dimensions, fromConcept, toConcept);
+                            break;
+                        case 'http://xbrl.org/int/dim/arcrole/all':
+                            // All relationship (for hypercubes)
+                            _this.addAllRelationship(dimensions, fromConcept, toConcept);
+                            break;
+                    }
+                }
+            });
+        });
+        return dimensions;
+    };
+    /**
+     * 4. LABEL LINKBASE - Provides human-readable labels
+     * Maps concepts to their display labels
+     */
+    XbrlRelationshipBuilder.prototype.buildLabelMappings = function () {
+        var _this = this;
+        var _a;
+        var labels = {};
+        (_a = this.labelLinkbase.labelLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+            var locators = _this.getLocators(link);
+            var arcs = _this.getLabelArcs(link);
+            var labelResources = _this.getLabelResources(link);
+            arcs.forEach(function (arc) {
+                var concept = _this.getConceptFromLocator(locators, arc.from);
+                var labelResource = labelResources.find(function (r) { return r.label === arc.to; });
+                if (concept && labelResource) {
+                    labels[concept] = labels[concept] || [];
+                    labels[concept].push({
+                        text: labelResource.text || '',
+                        role: labelResource.role || '',
+                        lang: labelResource.lang || 'en',
+                    });
+                }
+            });
+        });
+        return labels;
+    };
+    /**
+     * 5. RELATING FACTS TO DIMENSIONS
+     * Shows how actual data values relate to dimensional context
+     */
+    XbrlRelationshipBuilder.prototype.buildFactDimensionalMappings = function () {
+        var _this = this;
+        var factMappings = [];
+        this.instance.factElements.forEach(function (fact) {
+            var context = _this.instance.contexts.find(function (c) { return c.id === fact.contextRef; });
+            if (context) {
+                var dimensionalContext = {
+                    entity: context.entity.identifier.value,
+                    period: context.period,
+                    dimensions: context.entity.segment.map(function (seg) { return ({
+                        dimension: seg.dimension,
+                        member: seg.value,
+                    }); }),
+                };
+                factMappings.push({
+                    factName: fact.name,
+                    value: fact.text || '',
+                    unit: fact.unitRef || '',
+                    context: dimensionalContext,
+                    contextRef: fact.contextRef,
+                });
+            }
+        });
+        return factMappings;
+    };
+    /**
+     * 6. COMPREHENSIVE TAXONOMY MAPPING
+     * Combines all relationships into a unified structure
+     */
+    XbrlRelationshipBuilder.prototype.buildComprehensiveTaxonomyMap = function () {
+        var presentation = this.buildPresentationHierarchy();
+        var calculations = this.buildCalculationRelationships();
+        var dimensions = this.buildDimensionalRelationships();
+        var labels = this.buildLabelMappings();
+        var factMappings = this.buildFactDimensionalMappings();
+        return {
+            presentation: presentation,
+            calculations: calculations,
+            dimensions: dimensions,
+            labels: labels,
+            factMappings: factMappings,
+            // Helper methods to navigate relationships
+            getConceptChildren: function (concept) { var _a; return ((_a = presentation[concept]) === null || _a === void 0 ? void 0 : _a.children) || []; },
+            getConceptCalculation: function (concept) { return calculations[concept]; },
+            getConceptLabels: function (concept) { return labels[concept] || []; },
+            getFactsForConcept: function (concept) { return factMappings.filter(function (f) { return f.factName === concept; }); },
+            getDimensionsForConcept: function (concept) { return dimensions[concept]; },
+        };
+    };
+    // Helper methods
+    XbrlRelationshipBuilder.prototype.getLocators = function (link) {
+        return (link.loc || []).filter(function (item) { return item.type === 'locator'; });
+    };
+    XbrlRelationshipBuilder.prototype.getPresentationArcs = function (link) {
+        return (link.presentationArc || []).filter(function (item) { return item.type === 'arc'; });
+    };
+    XbrlRelationshipBuilder.prototype.getCalculationArcs = function (link) {
+        return (link.calculationArc || []).filter(function (item) { return item.type === 'arc'; });
+    };
+    XbrlRelationshipBuilder.prototype.getDefinitionArcs = function (link) {
+        return (link.definitionArc || []).filter(function (item) { return item.type === 'arc'; });
+    };
+    XbrlRelationshipBuilder.prototype.getLabelArcs = function (link) {
+        return (link.labelArc || []).filter(function (item) { return item.type === 'arc'; });
+    };
+    XbrlRelationshipBuilder.prototype.getLabelResources = function (link) {
+        return (link.label || []).filter(function (item) { return item.type === 'resource'; });
+    };
+    XbrlRelationshipBuilder.prototype.getConceptFromLocator = function (locators, label) {
+        var locator = locators.find(function (loc) { return loc.label === label; });
+        if (!locator)
+            return null;
+        // Extract concept name from href (e.g., "concept.xsd#us-gaap_Assets")
+        var match = locator.href.match(/#(.+)$/);
+        return match ? match[1] : null;
+    };
+    XbrlRelationshipBuilder.prototype.addHypercubeDimension = function (dimensions, hypercube, dimension) {
+        dimensions[hypercube] = dimensions[hypercube] || { type: 'hypercube', concept: hypercube, dimensions: [] };
+        dimensions[hypercube].dimensions = dimensions[hypercube].dimensions || [];
+        dimensions[hypercube].dimensions.push({ concept: dimension, type: 'dimension' });
+    };
+    XbrlRelationshipBuilder.prototype.addDimensionDomain = function (dimensions, dimension, domain) {
+        dimensions[dimension] = dimensions[dimension] || { type: 'dimension', concept: dimension, domains: [] };
+        dimensions[dimension].domains = dimensions[dimension].domains || [];
+        dimensions[dimension].domains.push({ concept: domain, type: 'domain' });
+    };
+    XbrlRelationshipBuilder.prototype.addDomainMember = function (dimensions, domain, member) {
+        dimensions[domain] = dimensions[domain] || { type: 'domain', concept: domain, members: [] };
+        dimensions[domain].members = dimensions[domain].members || [];
+        dimensions[domain].members.push({ concept: member, type: 'member' });
+    };
+    XbrlRelationshipBuilder.prototype.addAllRelationship = function (dimensions, from, to) {
+        // Handle 'all' relationships for hypercubes
+        dimensions[from] = dimensions[from] || { type: 'hypercube', concept: from, all: [] };
+        dimensions[from].all = dimensions[from].all || [];
+        dimensions[from].all.push({ concept: to, type: 'all' });
+    };
+    return XbrlRelationshipBuilder;
+}());
+exports.XbrlRelationshipBuilder = XbrlRelationshipBuilder;
+// Example usage:
+function exampleUsage(xbrlData) {
+    var builder = new XbrlRelationshipBuilder(xbrlData);
+    var taxonomyMap = builder.buildComprehensiveTaxonomyMap();
+    // Example: Find all children of "Assets" concept
+    var assetChildren = taxonomyMap.getConceptChildren('us-gaap:Assets');
+    console.log('Asset children:', assetChildren);
+    // Example: Get calculation for "Assets" (what adds up to total assets)
+    var assetCalculation = taxonomyMap.getConceptCalculation('us-gaap:Assets');
+    console.log('Asset calculation:', assetCalculation);
+    // Example: Get all labels for "Assets" concept
+    var assetLabels = taxonomyMap.getConceptLabels('us-gaap:Assets');
+    console.log('Asset labels:', assetLabels);
+    // Example: Get all facts for "Assets" concept
+    var assetFacts = taxonomyMap.getFactsForConcept('us-gaap:Assets');
+    console.log('Asset facts:', assetFacts);
+    // Example: Get dimensional information for a concept
+    var assetDimensions = taxonomyMap.getDimensionsForConcept('us-gaap:Assets');
+    console.log('Asset dimensions:', assetDimensions);
+    return taxonomyMap;
+}
+exports.exampleUsage = exampleUsage;
+function runExample() {
+    return __awaiter(this, void 0, void 0, function () {
+        var res, builder;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, __1.secEdgarApi.getDocumentXbrl({
+                        url: 'https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123.txt',
+                    })];
+                case 1:
+                    res = _a.sent();
+                    builder = new XbrlRelationshipBuilder({
+                        calculationLinkbase: res.linkbaseCalculation.xbrl,
+                        definitionLinkbase: res.linkbaseDefinition.xbrl,
+                        instance: res.instance.xbrl,
+                        labelLinkbase: res.linkbaseLabel.xbrl,
+                        presentationLinkbase: res.linkbasePresentation.xbrl,
+                        schema: res.schema.xbrl,
+                    });
+                    fs.writeFileSync('fact-dimensional-mappings.json', JSON.stringify(builder.buildFactDimensionalMappings(), null, 2));
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+runExample();

package/build/services/DocumentParser/XBRLParser/InstanceParser.js

@@ -62,22 +62,22 @@ var InstanceParser = /** @class */ (function () {
     };
     InstanceParser.prototype.parse = function (xml) {
         var _this = this;
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         var xbrl = util_xbrl_1.default.extractXbrlObject(this.xmlParser.parse(xml));
         var contexts = util_xbrl_1.default
-            .toArray((_b = (_a = xbrl === null || xbrl === void 0 ? void 0 : xbrl.context) !== null && _a !== void 0 ? _a : xbrl === null || xbrl === void 0 ? void 0 : xbrl['xbrli:context']) !== null && _b !== void 0 ? _b : [])
+            .toArray((_c = (_b = (_a = xbrl === null || xbrl === void 0 ? void 0 : xbrl.context) !== null && _a !== void 0 ? _a : xbrl === null || xbrl === void 0 ? void 0 : xbrl['xbrli:context']) !== null && _b !== void 0 ? _b : xbrl === null || xbrl === void 0 ? void 0 : xbrl['xbrl:context']) !== null && _c !== void 0 ? _c : [])
             .map(function (context) { return _this.parseContext(context); });
-        var units = util_xbrl_1.default.toArray((_c = xbrl === null || xbrl === void 0 ? void 0 : xbrl.unit) !== null && _c !== void 0 ? _c : []).map(function (unit) {
-            var _a, _b, _c, _d, _e;
+        var units = util_xbrl_1.default.toArray((_d = xbrl === null || xbrl === void 0 ? void 0 : xbrl.unit) !== null && _d !== void 0 ? _d : []).map(function (unit) {
+            var _a, _b, _c, _d, _e, _f, _g;
             return ({
                 id: (_a = unit['@_id']) !== null && _a !== void 0 ? _a : '',
-                measure: (_e = (_c = (_b = unit['xbrli:measure']) === null || _b === void 0 ? void 0 : _b['#text']) !== null && _c !== void 0 ? _c : (_d = unit['measure']) === null || _d === void 0 ? void 0 : _d['#text']) !== null && _e !== void 0 ? _e : '',
+                measure: (_g = (_e = (_c = (_b = unit['xbrli:measure']) === null || _b === void 0 ? void 0 : _b['#text']) !== null && _c !== void 0 ? _c : (_d = unit['measure']) === null || _d === void 0 ? void 0 : _d['#text']) !== null && _e !== void 0 ? _e : (_f = unit['xbrl:measure']) === null || _f === void 0 ? void 0 : _f['#text']) !== null && _g !== void 0 ? _g : '',
             });
         });
         var factElements = [];
         for (var name_1 in xbrl) {
-            for (var _i = 0, _d = util_xbrl_1.default.toArray(xbrl[name_1]); _i < _d.length; _i++) {
-                var element = _d[_i];
+            for (var _i = 0, _e = util_xbrl_1.default.toArray(xbrl[name_1]); _i < _e.length; _i++) {
+                var element = _e[_i];
                 if (!element['@_contextRef'])
                     continue;
                 var factElement = { name: name_1, id: '', contextRef: '' };

package/build/services/DocumentParser/parsers/parse-xbrl.js

@@ -24,6 +24,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseXbrl = void 0;
 var constants_1 = require("../../../util/constants");
+var util_xbrl_1 = require("../../../util/util-xbrl");
 var FactFiscalCalculator_1 = require("../../ReportRawBuilder/FactFiscalCalculator");
 var FactPeriodResolver_1 = require("../../ReportRawBuilder/FactPeriodResolver");
 var XBRLParser_1 = require("../XBRLParser/XBRLParser");
@@ -36,8 +37,8 @@ function isWithinDays(params) {
     return daysDiff < days;
 }
 function buildReportsFromFacts(params) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
-    var filing = params.filing, facts = params.facts, fiscalPeriod = params.fiscalPeriod, fiscalYear = params.fiscalYear, pathSeparator = params.pathSeparator, cikProp = params.cik, fiscalYearEnd = params.fiscalYearEnd;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x;
+    var filing = params.filing, facts = params.facts, fiscalPeriod = params.fiscalPeriod, fiscalYear = params.fiscalYear, pathSeparator = params.pathSeparator, cikProp = params.cik;
     var urlParts = (_a = filing === null || filing === void 0 ? void 0 : filing.url.split('/')) !== null && _a !== void 0 ? _a : [];
     var cik = cikProp !== null && cikProp !== void 0 ? cikProp : urlParts[(_b = urlParts.indexOf('data')) !== null && _b !== void 0 ? _b : -1];
     var reportFactValues = {
@@ -63,37 +64,38 @@ function buildReportsFromFacts(params) {
     var roundPlacesByName = new Map();
     var scaleByName = new Map();
     var isFocusFactByDateKey = new Map();
-    var fiscalYearEndMonth = Number(fiscalYearEnd.substring(0, 2));
-    var fiscalYearEndDay = Number(fiscalYearEnd.substring(2));
-    var fiscalCalculator = new FactFiscalCalculator_1.default({
-        filings: filing ? [filing] : undefined,
-        facts: facts,
-        fiscalYearEnd: { day: fiscalYearEndDay, month: fiscalYearEndMonth },
-    });
     var fiscalsByDateKey = new Map();
+    var focusPeriodByQuarter = {
+        1: 3,
+        2: 6,
+        3: 9,
+        4: 12,
+    };
     for (var _i = 0, facts_1 = facts; _i < facts_1.length; _i++) {
         var fact = facts_1[_i];
-        var dateKey = fact.start ? "".concat(fact.start, "_").concat(fact.end) : fact.end;
+        var period = FactPeriodResolver_1.default.getPeriod({ start: fact.start, end: fact.end });
+        var dateKey = fact.start ? "".concat(fact.start, "_").concat(fact.end, "_").concat(period) : "".concat(fact.end, "_").concat(period);
         if (!fiscalsByDateKey.has(dateKey)) {
-            var _w = fiscalCalculator.getFiscalYearQuarter({ dateStr: fact.end }), quarter = _w.quarter, year = _w.year;
-            var period = FactPeriodResolver_1.default.getPeriod({ end: fact.end, start: fact.start });
-            var fiscalPeriod_1 = (period === 12 && quarter === 4 ? 'FY' : "Q".concat(quarter));
-            fiscalsByDateKey.set(dateKey, { fiscalYear: year, fiscalPeriod: fiscalPeriod_1 });
+            var fiscalPeriod_1 = (period === 12 && fact.quarter === 4 ? 'FY' : "Q".concat(fact.quarter));
+            fiscalsByDateKey.set(dateKey, { fiscalYear: fact.fiscalYear, fiscalPeriod: fiscalPeriod_1 });
         }
         var isSplitFact = fact === splitFact;
-        var isFocusFact = (_h = isFocusFactByDateKey.get(dateKey)) !== null && _h !== void 0 ? _h : (isWithinDays({ dateA: fact.end, dateB: reportFocus.dateReport, days: 45 }) || isSplitFact);
-        (_j = reportByDateRange[dateKey]) !== null && _j !== void 0 ? _j : (reportByDateRange[dateKey] = {
+        var focusPeriod = (_h = focusPeriodByQuarter[fact.quarter]) !== null && _h !== void 0 ? _h : 0;
+        var isFocusPeriod = period === focusPeriod || period === 0;
+        var isFocusFact = (_j = isFocusFactByDateKey.get(dateKey)) !== null && _j !== void 0 ? _j : (isFocusPeriod &&
+            (isWithinDays({ dateA: fact.end, dateB: reportFocus.dateReport, days: 45 }) || isSplitFact));
+        (_k = reportByDateRange[dateKey]) !== null && _k !== void 0 ? _k : (reportByDateRange[dateKey] = {
             cik: reportFocus.cik,
-            url: '',
-            splitDate: (_k = splitFact === null || splitFact === void 0 ? void 0 : splitFact.end) !== null && _k !== void 0 ? _k : null,
+            url: (_l = filing === null || filing === void 0 ? void 0 : filing.url) !== null && _l !== void 0 ? _l : '',
+            splitDate: (_m = splitFact === null || splitFact === void 0 ? void 0 : splitFact.end) !== null && _m !== void 0 ? _m : null,
             splitRatio: (splitFact === null || splitFact === void 0 ? void 0 : splitFact.value) ? Number(splitFact.value) : null,
             dateFiled: reportFocus.dateFiled,
             dateReport: fact.end,
-            fiscalPeriod: (_l = fiscalsByDateKey.get(dateKey)) === null || _l === void 0 ? void 0 : _l.fiscalPeriod,
-            startDate: (_m = fact.start) !== null && _m !== void 0 ? _m : '',
+            fiscalPeriod: (_o = fiscalsByDateKey.get(dateKey)) === null || _o === void 0 ? void 0 : _o.fiscalPeriod,
+            startDate: (_p = fact.start) !== null && _p !== void 0 ? _p : '',
             endDate: fact.end,
-            fiscalYear: (_o = fiscalsByDateKey.get(dateKey)) === null || _o === void 0 ? void 0 : _o.fiscalYear,
-            period: FactPeriodResolver_1.default.getPeriod({ start: fact.start, end: fact.end }),
+            fiscalYear: (_q = fiscalsByDateKey.get(dateKey)) === null || _q === void 0 ? void 0 : _q.fiscalYear,
+            period: period,
             isCurrentPeriod: isFocusFact,
         });
         if (isFocusFact) {
@@ -103,11 +105,11 @@ function buildReportsFromFacts(params) {
             isFocusFactByDateKey.set(dateKey, isFocusFact);
         }
         var el = fact;
-        var scale = Number((_p = el.scale) !== null && _p !== void 0 ? _p : 0) || 0;
-        var decimals = Number((_q = el.decimals) !== null && _q !== void 0 ? _q : 0) || 0;
+        var scale = Number((_r = el.scale) !== null && _r !== void 0 ? _r : 0) || 0;
+        var decimals = Number((_s = el.decimals) !== null && _s !== void 0 ? _s : 0) || 0;
         var suffix = fact.name.includes(pathSeparator)
             ? null
-            : (_r = fact === null || fact === void 0 ? void 0 : fact.segments) === null || _r === void 0 ? void 0 : _r.map(function (_a) {
+            : (_t = fact === null || fact === void 0 ? void 0 : fact.segments) === null || _t === void 0 ? void 0 : _t.map(function (_a) {
                 var dimension = _a.dimension, value = _a.value;
                 return "".concat(dimension).concat(pathSeparator).concat(value);
             }).join(pathSeparator);
@@ -121,8 +123,8 @@ function buildReportsFromFacts(params) {
             var prevRounding = roundPlacesByName.get(prevFactKey);
             var prevScale = scaleByName.get(prevFactKey);
             var prevFact_1 = factByName.get(prevFactKey);
-            var prevUnit = (_t = (_s = prevFact_1 === null || prevFact_1 === void 0 ? void 0 : prevFact_1.unit) === null || _s === void 0 ? void 0 : _s.split('_').pop()) === null || _t === void 0 ? void 0 : _t.toLowerCase();
-            var unit = (_v = (_u = fact.unit) === null || _u === void 0 ? void 0 : _u.split('_').pop()) === null || _v === void 0 ? void 0 : _v.toLowerCase();
+            var prevUnit = (_v = (_u = prevFact_1 === null || prevFact_1 === void 0 ? void 0 : prevFact_1.unit) === null || _u === void 0 ? void 0 : _u.split('_').pop()) === null || _v === void 0 ? void 0 : _v.toLowerCase();
+            var unit = (_x = (_w = fact.unit) === null || _w === void 0 ? void 0 : _w.split('_').pop()) === null || _x === void 0 ? void 0 : _x.toLowerCase();
             var shouldSkip = [
                 (prevUnit === null || prevUnit === void 0 ? void 0 : prevUnit.length) === 3 && (unit === null || unit === void 0 ? void 0 : unit.length) === 3 && prevUnit !== unit && prevUnit === 'usd',
                 (prevRounding !== null && prevRounding !== void 0 ? prevRounding : 0) < roundPlaces,
@@ -149,33 +151,46 @@ function buildReportsFromFacts(params) {
     return { reportFocus: reportFocus, reportByDateRange: reportByDateRange, factsFiltered: Array.from(factByName.values()) };
 }
 function parseXbrl(params) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     var parser = new XBRLParser_1.default();
-    var xml = params.xml, _o = params.includeReport, includeReport = _o === void 0 ? true : _o, options = __rest(params, ["xml", "includeReport"]);
+    var xml = params.xml, _r = params.includeReport, includeReport = _r === void 0 ? true : _r, options = __rest(params, ["xml", "includeReport"]);
     var response = parser.parse(xml, options);
-    var _p = (_b = (_a = response.instance) === null || _a === void 0 ? void 0 : _a.xbrl) !== null && _b !== void 0 ? _b : {}, _q = _p.contexts, contexts = _q === void 0 ? [] : _q, _r = _p.factElements, factElements = _r === void 0 ? [] : _r;
+    var _s = (_b = (_a = response.instance) === null || _a === void 0 ? void 0 : _a.xbrl) !== null && _b !== void 0 ? _b : {}, _t = _s.contexts, contexts = _t === void 0 ? [] : _t, _u = _s.factElements, factElements = _u === void 0 ? [] : _u;
+    var labelByTaxonomy = (0, util_xbrl_1.getLabelByTaxonomy)((_d = (_c = response.linkbaseLabel) === null || _c === void 0 ? void 0 : _c.xbrl) !== null && _d !== void 0 ? _d : {});
     var contextById = new Map();
     contexts.forEach(function (context) { return contextById.set(context.id, context); });
     var cik = response.header.cik;
     var accessionNumber = response.header.accessionNumber;
     var accessionNumberNoHyphens = accessionNumber.replace(/-/g, '');
+    var fiscalCalculator = new FactFiscalCalculator_1.default({
+        fiscalYearEnd: {
+            day: Number(response.header.fiscalYearEnd.substring(2)),
+            month: Number(response.header.fiscalYearEnd.substring(0, 2)),
+        },
+    });
     var facts = [];
     for (var _i = 0, factElements_1 = factElements; _i < factElements_1.length; _i++) {
         var fact = factElements_1[_i];
         var context = contextById.get(fact.contextRef);
-        var end = (_d = (_c = context === null || context === void 0 ? void 0 : context.period.endDate) !== null && _c !== void 0 ? _c : context === null || context === void 0 ? void 0 : context.period.instant) !== null && _d !== void 0 ? _d : '';
+        var end = (_f = (_e = context === null || context === void 0 ? void 0 : context.period.endDate) !== null && _e !== void 0 ? _e : context === null || context === void 0 ? void 0 : context.period.instant) !== null && _f !== void 0 ? _f : '';
         var start = context === null || context === void 0 ? void 0 : context.period.startDate;
+        var _v = fiscalCalculator.getFiscalYearQuarter({ dateStr: end }), quarter = _v.quarter, year = _v.year;
         var factParsed = {
             cik: cik,
             end: end,
             filed: response.header.filingDate,
             name: fact.name,
-            unit: (_e = fact.unitRef) !== null && _e !== void 0 ? _e : 'pure',
+            unit: (_g = fact.unitRef) !== null && _g !== void 0 ? _g : 'pure',
             value: isNaN(Number(fact.text)) ? String(fact.text) : Number(fact.text),
             accn: accessionNumber,
             form: response.header.form,
-            segments: (_f = context === null || context === void 0 ? void 0 : context.entity.segment) !== null && _f !== void 0 ? _f : [],
+            segments: (_h = context === null || context === void 0 ? void 0 : context.entity.segment) !== null && _h !== void 0 ? _h : [],
             start: start,
+            contextRef: fact.contextRef,
+            label: (_j = labelByTaxonomy[fact.name]) !== null && _j !== void 0 ? _j : fact.name,
+            period: FactPeriodResolver_1.default.getPeriod({ start: start, end: end }),
+            quarter: quarter,
+            fiscalYear: year,
         };
         if (factParsed.decimals) {
             factParsed.decimals = Number(fact.decimals);
@@ -190,28 +205,21 @@ function parseXbrl(params) {
     var fiscalYear = fiscalYearFact ? Number(fiscalYearFact.value) : 0;
     var fiscalPeriod = fiscalPeriodFact ? fiscalPeriodFact.value : 'FY';
     if (!fiscalPeriodFact || !fiscalYearFact) {
-        var fiscalCalculator = new FactFiscalCalculator_1.default({
-            fiscalYearEnd: {
-                day: Number(response.header.fiscalYearEnd.substring(2)),
-                month: Number(response.header.fiscalYearEnd.substring(0, 2)),
-            },
-        });
-        var reportDate = (_g = response.header.reportDate) !== null && _g !== void 0 ? _g : (_j = (_h = response.instance) === null || _h === void 0 ? void 0 : _h.xbrl.factElements.find(function (f) { return f.name === 'dei:DocumentPeriodEndDate'; })) === null || _j === void 0 ? void 0 : _j.text;
+        var reportDate = (_k = response.header.reportDate) !== null && _k !== void 0 ? _k : (_m = (_l = response.instance) === null || _l === void 0 ? void 0 : _l.xbrl.factElements.find(function (f) { return f.name === 'dei:DocumentPeriodEndDate'; })) === null || _m === void 0 ? void 0 : _m.text;
         if (!reportDate) {
             throw new Error("Report date not found. Unable to determine fiscal year and period. accn: ".concat(accessionNumber));
         }
-        var _s = fiscalCalculator.getFiscalYearQuarter({ dateStr: reportDate !== null && reportDate !== void 0 ? reportDate : '' }), quarter = _s.quarter, year = _s.year;
+        var _w = fiscalCalculator.getFiscalYearQuarter({ dateStr: reportDate !== null && reportDate !== void 0 ? reportDate : '' }), quarter = _w.quarter, year = _w.year;
         fiscalYear = year;
         fiscalPeriod = (quarter === 4 ? 'FY' : "Q".concat(quarter));
     }
     var factsForBuilder = includeReport ? facts : [];
-    var _t = buildReportsFromFacts({
+    var _x = buildReportsFromFacts({
         facts: factsForBuilder,
         pathSeparator: '>',
-        fiscalPeriod: (_k = factsForBuilder.find(function (f) { return f.name === 'dei:DocumentFiscalPeriodFocus'; })) === null || _k === void 0 ? void 0 : _k.value,
-        fiscalYear: Number((_m = (_l = factsForBuilder.find(function (f) { return f.name === 'dei:DocumentFiscalYearFocus'; })) === null || _l === void 0 ? void 0 : _l.value) !== null && _m !== void 0 ? _m : 0),
+        fiscalPeriod: (_o = factsForBuilder.find(function (f) { return f.name === 'dei:DocumentFiscalPeriodFocus'; })) === null || _o === void 0 ? void 0 : _o.value,
+        fiscalYear: Number((_q = (_p = factsForBuilder.find(function (f) { return f.name === 'dei:DocumentFiscalYearFocus'; })) === null || _p === void 0 ? void 0 : _p.value) !== null && _q !== void 0 ? _q : 0),
         cik: response.header.cik,
-        fiscalYearEnd: response.header.fiscalYearEnd,
         filing: {
             acceptanceDateTime: response.header.acceptanceDatetime,
             accessionNumber: accessionNumber,
@@ -230,7 +238,7 @@ function parseXbrl(params) {
             url: "https://www.sec.gov/Archives/edgar/data/".concat(cik, "/").concat(accessionNumberNoHyphens, "/").concat(accessionNumber, ".txt"),
             urlPrimaryDocument: '',
         },
-    }), factsFiltered = _t.factsFiltered, reportFocus = _t.reportFocus, reportByDateRange = _t.reportByDateRange;
+    }), factsFiltered = _x.factsFiltered, reportFocus = _x.reportFocus, reportByDateRange = _x.reportByDateRange;
     // Some concepts have members, but do not have a sum. add the sum to the report.
     var periodReports = Object.values(reportByDateRange);
     return __assign(__assign({}, response), { fiscalYear: fiscalYear, fiscalPeriod: fiscalPeriod, facts: factsFiltered, report: factsFiltered.length > 0 ? reportFocus : null, xml: xml, periodReports: periodReports });

package/build/services/SecEdgarApi/SecEdgarApi.d.ts

@@ -300,6 +300,7 @@ export default class SecEdgarApi {
         formType?: DailyFilingFormType;
         /** max 5 */
         lookbackDays?: number;
+        startsWith?: string;
     }): Promise<{
         date: string;
         matchCount: number;

package/build/services/SecEdgarApi/SecEdgarApi.js

@@ -595,11 +595,11 @@ var SecEdgarApi = /** @class */ (function () {
     SecEdgarApi.prototype.getCurrentFilingsDaily = function (params) {
         var _a;
         return __awaiter(this, void 0, void 0, function () {
-            var _b, _c, formType, _d, lookbackDays, indexByFormType, indexFormType, url, xml;
-            return __generator(this, function (_e) {
-                switch (_e.label) {
+            var _b, _c, formType, _d, lookbackDays, _e, startsWith, indexByFormType, indexFormType, url, xml;
+            return __generator(this, function (_f) {
+                switch (_f.label) {
                     case 0:
-                        _b = params !== null && params !== void 0 ? params : {}, _c = _b.formType, formType = _c === void 0 ? 'ALL' : _c, _d = _b.lookbackDays, lookbackDays = _d === void 0 ? 0 : _d;
+                        _b = params !== null && params !== void 0 ? params : {}, _c = _b.formType, formType = _c === void 0 ? 'ALL' : _c, _d = _b.lookbackDays, lookbackDays = _d === void 0 ? 0 : _d, _e = _b.startsWith, startsWith = _e === void 0 ? '' : _e;
                         if (lookbackDays > 5) {
                             throw new Error("lookbackDays must be <= 5. Received ".concat(lookbackDays));
                         }
@@ -613,10 +613,10 @@ var SecEdgarApi = /** @class */ (function () {
                             ALL: 6,
                         };
                         indexFormType = (_a = indexByFormType[formType]) !== null && _a !== void 0 ? _a : 0;
-                        url = "".concat(this.baseUrlSec, "/cgi-bin/current?q1=").concat(lookbackDays, "&q2=").concat(indexFormType);
+                        url = "".concat(this.baseUrlSec, "/cgi-bin/current?q1=").concat(lookbackDays, "&q2=").concat(indexFormType, "&q3=").concat(startsWith);
                         return [4 /*yield*/, this.request(url, true)];
                     case 1:
-                        xml = (_e.sent());
+                        xml = (_f.sent());
                         return [2 /*return*/, this.documentParser.parseCurrentFilingsDaily({ xml: xml })];
                 }
             });

package/build/types/company-facts.type.d.ts

@@ -79,6 +79,11 @@ export interface FactItemExtended extends FactItem {
     isCurrentPeriod?: boolean;
     decimals?: number;
     scale?: number;
+    contextRef: string;
+    label: string;
+    period: number;
+    quarter: number;
+    fiscalYear: number;
 }
 export interface FactItemWithFiscals extends FactItem {
     fiscalPeriod: FiscalPeriod;

package/build/util/util-xbrl.d.ts

@@ -0,0 +1,3 @@
+import { XbrlLinkbase } from '../types/xbrl.type';
+export declare function getLabelByTaxonomy(labelLinkbase: XbrlLinkbase): Record<string, string>;
+export declare function getTaxonomyFromId(id: string): string;

package/build/util/util-xbrl.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTaxonomyFromId = exports.getLabelByTaxonomy = void 0;
+function getLabelByTaxonomy(labelLinkbase) {
+    var _a;
+    var labelByTaxonomy = {};
+    (_a = labelLinkbase.labelLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var _a;
+        (_a = link.label) === null || _a === void 0 ? void 0 : _a.forEach(function (_a) {
+            var _b = _a.label, label = _b === void 0 ? '' : _b, _c = _a.text, text = _c === void 0 ? '' : _c, _d = _a.role, role = _d === void 0 ? '' : _d;
+            var taxonomy = getTaxonomyFromId(label);
+            // prefer terseLabel over regular label
+            if (role.endsWith('terseLabel') || !labelByTaxonomy[taxonomy]) {
+                labelByTaxonomy[taxonomy] = text;
+            }
+        });
+    });
+    return labelByTaxonomy;
+}
+exports.getLabelByTaxonomy = getLabelByTaxonomy;
+function getTaxonomyFromId(id) {
+    return id.split('_').slice(1, 3).join(':');
+}
+exports.getTaxonomyFromId = getTaxonomyFromId;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sec-edgar-api",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Fetch and parse SEC earnings reports and other filings. Useful for financial analysis.",
     "main": "build/index.js",
     "author": "Andrew Evers (https://github.com/andyevers)",