altium-toolkit 1.1.2 → 1.1.22

package/src/core/altium/SourceBundleExporter.mjs

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Exports normalized source component bundles as deterministic file entries.
+ */
+export class SourceBundleExporter {
+    /**
+     * Exports one source bundle.
+     * @param {object} componentBundle Component bundle or raw response.
+     * @param {{ includeModels?: boolean }} [options] Export options.
+     * @returns {{ manifest: object, entries: { path: string, bytes: Uint8Array, contentType: string }[] }}
+     */
+    static export(componentBundle, options = {}) {
+        const bundle =
+            SourceComponentBundleNormalizer.normalize(componentBundle)
+        const includeModels = options.includeModels !== false
+        const manifest = SourceBundleExporter.#buildManifest(
+            bundle,
+            includeModels
+        )
+        const entries = [
+            SourceBundleExporter.#jsonEntry('manifest.json', manifest),
+            SourceBundleExporter.#jsonEntry(
+                'source/source.json',
+                bundle.sourceJson
+            )
+        ]
+
+        if (includeModels) {
+            entries.push(
+                ...bundle.models.map((model) => ({
+                    path:
+                        'models/' +
+                        SourceBundleExporter.#safeFileName(model.name),
+                    bytes: model.bytes,
+                    contentType: SourceBundleExporter.#modelContentType(model)
+                }))
+            )
+        }
+
+        return {
+            manifest,
+            entries: entries.sort((left, right) =>
+                left.path.localeCompare(right.path)
+            )
+        }
+    }
+
+    /**
+     * Builds a deterministic manifest.
+     * @param {object} bundle Normalized bundle.
+     * @param {boolean} includeModels Whether model assets are included.
+     * @returns {object}
+     */
+    static #buildManifest(bundle, includeModels) {
+        return {
+            schema: 'ecad-source-bundle-v1',
+            component: {
+                id: bundle.id,
+                name: bundle.name,
+                symbolName: bundle.symbol.name,
+                footprintName: bundle.footprint.name
+            },
+            assets: includeModels
+                ? bundle.models.map((model) => ({
+                      name: model.name,
+                      format: model.format,
+                      path:
+                          'models/' +
+                          SourceBundleExporter.#safeFileName(model.name),
+                      byteLength: model.bytes.byteLength
+                  }))
+                : []
+        }
+    }
+
+    /**
+     * Creates one JSON entry.
+     * @param {string} path Entry path.
+     * @param {object} value JSON value.
+     * @returns {{ path: string, bytes: Uint8Array, contentType: string }}
+     */
+    static #jsonEntry(path, value) {
+        return {
+            path,
+            bytes: new TextEncoder().encode(
+                SourceBundleExporter.#stableStringify(value) + '\n'
+            ),
+            contentType: 'application/json'
+        }
+    }
+
+    /**
+     * Returns a stable JSON string with sorted object keys.
+     * @param {any} value JSON-compatible value.
+     * @returns {string}
+     */
+    static #stableStringify(value) {
+        return JSON.stringify(SourceBundleExporter.#sortJson(value), null, 2)
+    }
+
+    /**
+     * Recursively sorts JSON object keys.
+     * @param {any} value JSON-compatible value.
+     * @returns {any}
+     */
+    static #sortJson(value) {
+        if (Array.isArray(value)) {
+            return value.map((entry) => SourceBundleExporter.#sortJson(entry))
+        }
+
+        if (
+            value &&
+            typeof value === 'object' &&
+            !(value instanceof Uint8Array)
+        ) {
+            return Object.fromEntries(
+                Object.keys(value)
+                    .sort()
+                    .map((key) => [
+                        key,
+                        SourceBundleExporter.#sortJson(value[key])
+                    ])
+            )
+        }
+
+        return value
+    }
+
+    /**
+     * Returns a safe bundle file name.
+     * @param {string} name Raw file name.
+     * @returns {string}
+     */
+    static #safeFileName(name) {
+        return String(name || 'model.step').replace(
+            /[\\/:\u0000-\u001f]/gu,
+            '_'
+        )
+    }
+
+    /**
+     * Resolves a model content type.
+     * @param {object} model Model descriptor.
+     * @returns {string}
+     */
+    static #modelContentType(model) {
+        if (model.format === 'obj') return 'model/obj'
+        if (model.format === 'mtl') return 'text/plain'
+        return 'model/step'
+    }
+}

package/src/core/altium/SourceComponentBundleNormalizer.mjs

@@ -0,0 +1,295 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Normalizes component-provider responses into one exporter-ready bundle.
+ */
+export class SourceComponentBundleNormalizer {
+    /**
+     * Normalizes a raw provider response.
+     * @param {object} rawComponent Raw component response.
+     * @returns {{ id: string, name: string, metadata: object, symbol: object, footprint: object, models: object[], sourceJson: object, diagnostics: object[] }}
+     */
+    static normalize(rawComponent = {}) {
+        const source = SourceComponentBundleNormalizer.#unwrap(rawComponent)
+        const metadata = SourceComponentBundleNormalizer.#normalizeMetadata(
+            rawComponent,
+            source
+        )
+        const symbol = SourceComponentBundleNormalizer.#normalizeSymbol(source)
+        const footprint =
+            SourceComponentBundleNormalizer.#normalizeFootprint(source)
+        const models = SourceComponentBundleNormalizer.#normalizeModels(source)
+        const bundle = {
+            id: SourceComponentBundleNormalizer.#firstString(
+                source.id,
+                source.uuid,
+                source.componentId,
+                rawComponent.id,
+                rawComponent.uuid,
+                metadata.partNumber,
+                metadata.name,
+                'component'
+            ),
+            name: SourceComponentBundleNormalizer.#firstString(
+                source.name,
+                source.title,
+                rawComponent.name,
+                rawComponent.title,
+                metadata.name,
+                metadata.partNumber,
+                'Component'
+            ),
+            metadata,
+            symbol,
+            footprint,
+            models,
+            sourceJson: rawComponent,
+            diagnostics: []
+        }
+
+        bundle.diagnostics =
+            SourceComponentBundleNormalizer.#buildDiagnostics(bundle)
+
+        return bundle
+    }
+
+    /**
+     * Unwraps common response envelopes.
+     * @param {object} rawComponent Raw component response.
+     * @returns {object}
+     */
+    static #unwrap(rawComponent) {
+        return (
+            rawComponent?.data?.component ||
+            rawComponent?.data?.result ||
+            rawComponent?.data ||
+            rawComponent?.result ||
+            rawComponent?.component ||
+            rawComponent ||
+            {}
+        )
+    }
+
+    /**
+     * Normalizes component metadata.
+     * @param {object} rawComponent Raw component response.
+     * @param {object} source Unwrapped response.
+     * @returns {object}
+     */
+    static #normalizeMetadata(rawComponent, source) {
+        return {
+            ...(rawComponent?.metadata || {}),
+            ...(source?.metadata || {}),
+            ...(source?.attributes || {})
+        }
+    }
+
+    /**
+     * Normalizes the schematic symbol portion of a bundle.
+     * @param {object} source Unwrapped response.
+     * @returns {{ name: string, pins: object[], primitives: object[], raw: object }}
+     */
+    static #normalizeSymbol(source) {
+        const symbol = source?.symbol || source?.schematic || {}
+
+        return {
+            name: SourceComponentBundleNormalizer.#firstString(
+                symbol.name,
+                symbol.title,
+                source.symbolName,
+                source.name,
+                'Component'
+            ),
+            pins: SourceComponentBundleNormalizer.#array(
+                symbol.pins || symbol.pinList
+            ),
+            primitives: SourceComponentBundleNormalizer.#array(
+                symbol.primitives || symbol.shapes || symbol.graphics
+            ),
+            raw: symbol
+        }
+    }
+
+    /**
+     * Normalizes the PCB footprint portion of a bundle.
+     * @param {object} source Unwrapped response.
+     * @returns {{ name: string, pads: object[], tracks: object[], arcs: object[], fills: object[], texts: object[], primitives: object[], raw: object }}
+     */
+    static #normalizeFootprint(source) {
+        const footprint = source?.footprint || source?.package || {}
+
+        return {
+            name: SourceComponentBundleNormalizer.#firstString(
+                footprint.name,
+                footprint.title,
+                source.footprintName,
+                source.packageName,
+                source.name,
+                'Component'
+            ),
+            pads: SourceComponentBundleNormalizer.#array(footprint.pads),
+            tracks: SourceComponentBundleNormalizer.#array(footprint.tracks),
+            arcs: SourceComponentBundleNormalizer.#array(footprint.arcs),
+            fills: SourceComponentBundleNormalizer.#array(footprint.fills),
+            texts: SourceComponentBundleNormalizer.#array(footprint.texts),
+            primitives: SourceComponentBundleNormalizer.#array(
+                footprint.primitives || footprint.shapes
+            ),
+            raw: footprint
+        }
+    }
+
+    /**
+     * Normalizes model asset descriptors.
+     * @param {object} source Unwrapped response.
+     * @returns {object[]}
+     */
+    static #normalizeModels(source) {
+        const models = SourceComponentBundleNormalizer.#array(
+            source?.models || source?.modelAssets || source?.assets
+        )
+
+        return models
+            .map((model, index) =>
+                SourceComponentBundleNormalizer.#normalizeModel(model, index)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes one model asset descriptor.
+     * @param {object} model Raw model asset.
+     * @param {number} index Model index.
+     * @returns {object | null}
+     */
+    static #normalizeModel(model, index) {
+        if (!model || typeof model !== 'object') {
+            return null
+        }
+
+        const name = SourceComponentBundleNormalizer.#firstString(
+            model.name,
+            model.fileName,
+            model.path,
+            'model-' + index + '.step'
+        )
+        const bytes =
+            SourceComponentBundleNormalizer.#normalizeModelBytes(model)
+
+        return {
+            id: SourceComponentBundleNormalizer.#firstString(
+                model.id,
+                model.uuid,
+                'model-' + index
+            ),
+            name,
+            format: SourceComponentBundleNormalizer.#normalizeFormat(
+                model.format,
+                name
+            ),
+            bytes,
+            text:
+                typeof model.text === 'string'
+                    ? model.text
+                    : new TextDecoder().decode(bytes),
+            sourceUrl: SourceComponentBundleNormalizer.#firstString(
+                model.url,
+                model.downloadUrl,
+                model.sourceUrl
+            ),
+            raw: model
+        }
+    }
+
+    /**
+     * Normalizes one model payload into bytes.
+     * @param {object} model Raw model asset.
+     * @returns {Uint8Array}
+     */
+    static #normalizeModelBytes(model) {
+        if (model.bytes instanceof Uint8Array) {
+            return new Uint8Array(model.bytes)
+        }
+
+        if (model.arrayBuffer instanceof ArrayBuffer) {
+            return new Uint8Array(model.arrayBuffer)
+        }
+
+        if (typeof model.text === 'string') {
+            return new TextEncoder().encode(model.text)
+        }
+
+        if (typeof model.content === 'string') {
+            return new TextEncoder().encode(model.content)
+        }
+
+        return new Uint8Array(0)
+    }
+
+    /**
+     * Normalizes one model format id.
+     * @param {any} format Explicit format.
+     * @param {string} name File name.
+     * @returns {string}
+     */
+    static #normalizeFormat(format, name) {
+        const explicit = String(format || '').toLowerCase()
+        if (explicit) {
+            return explicit.replace(/^\./u, '')
+        }
+
+        const extension = String(name || '')
+            .split('.')
+            .at(-1)
+        return extension ? extension.toLowerCase() : 'step'
+    }
+
+    /**
+     * Builds bundle diagnostics.
+     * @param {object} bundle Normalized bundle.
+     * @returns {object[]}
+     */
+    static #buildDiagnostics(bundle) {
+        const diagnostics = []
+
+        if (!bundle.symbol.raw || !Object.keys(bundle.symbol.raw).length) {
+            diagnostics.push({
+                severity: 'warning',
+                message: 'No schematic symbol data was present.'
+            })
+        }
+
+        if (
+            !bundle.footprint.raw ||
+            !Object.keys(bundle.footprint.raw).length
+        ) {
+            diagnostics.push({
+                severity: 'warning',
+                message: 'No PCB footprint data was present.'
+            })
+        }
+
+        return diagnostics
+    }
+
+    /**
+     * Returns an array for a possible array value.
+     * @param {any} value Possible array.
+     * @returns {object[]}
+     */
+    static #array(value) {
+        return Array.isArray(value) ? value : []
+    }
+
+    /**
+     * Returns the first non-empty string.
+     * @param {...any} values Candidate values.
+     * @returns {string}
+     */
+    static #firstString(...values) {
+        const value = values.find((candidate) => String(candidate || '').trim())
+        return String(value || '')
+    }
+}

package/src/core/altium/SourceComponentClient.mjs

@@ -0,0 +1,239 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Fetches source component records through an injected HTTP fetcher.
+ */
+export class SourceComponentClient {
+    #baseUrl
+
+    #componentPath
+
+    #fetcher
+
+    #headers
+
+    #modelPath
+
+    #retryCount
+
+    #retryDelayMs
+
+    #searchPath
+
+    /**
+     * @param {{ fetcher?: Function, baseUrl?: string, searchPath?: string, componentPath?: string, modelPath?: string, retryCount?: number, retryDelayMs?: number, headers?: Record<string, string> }} [options] Client options.
+     */
+    constructor(options = {}) {
+        this.#fetcher = options.fetcher || null
+        this.#baseUrl = String(options.baseUrl || '').replace(/\/$/u, '')
+        this.#searchPath = String(
+            options.searchPath || '/api/components/search'
+        )
+        this.#componentPath = String(
+            options.componentPath || '/api/components/{id}'
+        )
+        this.#modelPath = String(options.modelPath || '/api/models/{name}')
+        this.#retryCount = Math.max(0, Number(options.retryCount || 0))
+        this.#retryDelayMs = Math.max(0, Number(options.retryDelayMs || 0))
+        this.#headers = { ...(options.headers || {}) }
+    }
+
+    /**
+     * Searches provider components.
+     * @param {string} query Search query.
+     * @param {{ limit?: number }} [options] Search options.
+     * @returns {Promise<{ id: string, name: string, raw: object }[]>}
+     */
+    async searchComponents(query, options = {}) {
+        this.#assertFetcher()
+        const url = new URL(this.#baseUrl + this.#searchPath)
+        url.searchParams.set('q', String(query || ''))
+        if (options.limit) {
+            url.searchParams.set('limit', String(options.limit))
+        }
+        const json = await this.#requestJson(url)
+        const rows = SourceComponentClient.#extractRows(json)
+
+        return rows.map((row) => ({
+            id: String(row.id || row.uuid || row.componentId || ''),
+            name: String(row.name || row.title || row.id || ''),
+            raw: row
+        }))
+    }
+
+    /**
+     * Fetches and normalizes one source component bundle.
+     * @param {string} id Component identifier.
+     * @returns {Promise<object>}
+     */
+    async fetchComponentBundle(id) {
+        const json = await this.#requestJson(
+            this.#resolveTemplateUrl(this.#componentPath, { id })
+        )
+
+        return SourceComponentBundleNormalizer.normalize(json)
+    }
+
+    /**
+     * Fetches a model text asset.
+     * @param {string} urlOrName URL or model name.
+     * @returns {Promise<string>}
+     */
+    async fetchTextAsset(urlOrName) {
+        const response = await this.#fetchWithRetry(
+            this.#resolveAssetUrl(urlOrName)
+        )
+        if (typeof response.text === 'function') {
+            return response.text()
+        }
+
+        const bytes = await SourceComponentClient.#responseBytes(response)
+        return new TextDecoder().decode(bytes)
+    }
+
+    /**
+     * Fetches a model binary asset.
+     * @param {string} urlOrName URL or model name.
+     * @returns {Promise<Uint8Array>}
+     */
+    async fetchBinaryAsset(urlOrName) {
+        return SourceComponentClient.#responseBytes(
+            await this.#fetchWithRetry(this.#resolveAssetUrl(urlOrName))
+        )
+    }
+
+    /**
+     * Requests JSON.
+     * @param {URL | string} url Request URL.
+     * @returns {Promise<any>}
+     */
+    async #requestJson(url) {
+        const response = await this.#fetchWithRetry(url)
+        if (typeof response.json === 'function') {
+            return response.json()
+        }
+
+        return JSON.parse(await response.text())
+    }
+
+    /**
+     * Fetches with retry.
+     * @param {URL | string} url Request URL.
+     * @returns {Promise<object>}
+     */
+    async #fetchWithRetry(url) {
+        this.#assertFetcher()
+
+        let lastError = null
+        for (let attempt = 0; attempt <= this.#retryCount; attempt += 1) {
+            try {
+                const response = await this.#fetcher(String(url), {
+                    headers: this.#headers
+                })
+                if (response?.ok !== false) {
+                    return response
+                }
+                lastError = new Error(
+                    'Source component request failed with status ' +
+                        String(response.status || 0)
+                )
+            } catch (error) {
+                lastError = error
+            }
+
+            if (attempt < this.#retryCount && this.#retryDelayMs) {
+                await SourceComponentClient.#delay(this.#retryDelayMs)
+            }
+        }
+
+        throw lastError
+    }
+
+    /**
+     * Asserts that a fetcher was injected.
+     * @returns {void}
+     */
+    #assertFetcher() {
+        if (typeof this.#fetcher !== 'function') {
+            throw new Error('SourceComponentClient fetcher is required.')
+        }
+    }
+
+    /**
+     * Resolves a URL template.
+     * @param {string} template URL template.
+     * @param {Record<string, string>} values Template values.
+     * @returns {URL}
+     */
+    #resolveTemplateUrl(template, values) {
+        const path = Object.entries(values).reduce(
+            (nextPath, [key, value]) =>
+                nextPath.replaceAll(
+                    '{' + key + '}',
+                    encodeURIComponent(String(value || ''))
+                ),
+            template
+        )
+
+        return new URL(this.#baseUrl + path)
+    }
+
+    /**
+     * Resolves a model asset URL or name.
+     * @param {string} urlOrName URL or model name.
+     * @returns {URL}
+     */
+    #resolveAssetUrl(urlOrName) {
+        const value = String(urlOrName || '')
+        if (/^https?:\/\//iu.test(value)) {
+            return new URL(value)
+        }
+
+        return this.#resolveTemplateUrl(this.#modelPath, { name: value })
+    }
+
+    /**
+     * Extracts search rows from common response shapes.
+     * @param {any} json Response JSON.
+     * @returns {object[]}
+     */
+    static #extractRows(json) {
+        const rows =
+            json?.results ||
+            json?.items ||
+            json?.data?.results ||
+            json?.data?.items ||
+            json?.data ||
+            json
+
+        return Array.isArray(rows) ? rows : []
+    }
+
+    /**
+     * Reads response bytes.
+     * @param {object} response Response-like object.
+     * @returns {Promise<Uint8Array>}
+     */
+    static async #responseBytes(response) {
+        if (typeof response.arrayBuffer === 'function') {
+            return new Uint8Array(await response.arrayBuffer())
+        }
+
+        return new TextEncoder().encode(await response.text())
+    }
+
+    /**
+     * Delays retry execution.
+     * @param {number} milliseconds Delay in milliseconds.
+     * @returns {Promise<void>}
+     */
+    static #delay(milliseconds) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, milliseconds)
+        })
+    }
+}