'use strict'; /** * build-signal-mdx.js * * Generates per-group MDX files for the Smartcar Signals & Attributes section, * sourced from specs/vehicle-signals.yml (built by build-vehicle-signals-spec.js). * * Outputs: * api-reference/signals/.mdx — one page per signal group * snippets/signals.mdx — bullet list of group links * docs.json — nav updated with generated pages * * Run with: node scripts/build-signal-mdx.js */ const fs = require('fs'); const path = require('path'); const yaml = require('js-yaml'); const VEHICLE_SIGNALS_PATH = path.resolve(__dirname, '../specs/vehicle-signals.yml'); const OUTPUT_DIR = path.resolve(__dirname, '../api-reference/signals'); const SNIPPETS_DIR = path.resolve(__dirname, '../snippets'); const DOCS_JSON_PATH = path.resolve(__dirname, '../docs.json'); const SCHEMA_NAV_PATH = 'api-reference/signals/schema'; // --------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------- function loadYaml(filePath) { return yaml.load(fs.readFileSync(filePath, 'utf8')); } function generateParamField(name, prop, isRequired, indent = ' ') { const type = prop.type || 'object'; const lines = []; lines.push(`${indent}`); if (prop.description) { lines.push(`${indent} ${prop.description.replace(/\n/g, ' ')}`); } if (prop.enum && Array.isArray(prop.enum)) { lines.push(`${indent} `); lines.push(`${indent} **Possible values:** ${prop.enum.map(v => `\`${v}\``).join(', ')}`); } lines.push(`${indent}`); return lines; } function handleNestedProperties(properties, required = [], indent = ' ') { const lines = []; Object.entries(properties).forEach(([propName, prop]) => { if (prop.type === 'array' && prop.items && prop.items.properties) { lines.push(...generateParamField(propName, prop, required.includes(propName), indent)); lines.push(`${indent}`); lines.push(...handleNestedProperties(prop.items.properties, prop.items.required || [], indent + ' ')); lines.push(`${indent}`); } else if (prop.type === 'object' && prop.properties) { lines.push(...generateParamField(propName, prop, required.includes(propName), indent)); lines.push(`${indent}`); lines.push(...handleNestedProperties(prop.properties, prop.required || [], indent + ' ')); lines.push(`${indent}`); } else { lines.push(...generateParamField(propName, prop, required.includes(propName), indent)); } }); return lines; } // --------------------------------------------------------------------------- // MDX generation — one file per group // --------------------------------------------------------------------------- function writeGroupMdx(groupName, signals, outputDir) { console.log(`\n🔍 Processing group: ${groupName} (${signals.length} signals)`); const lines = []; lines.push('---'); lines.push(`title: "${groupName} Signals"`); lines.push(`sidebarTitle: "${groupName}"`); lines.push('---\n'); signals.forEach(({ signalCode, signalName, description, bodySchema }) => { console.log(` ${signalName} (${signalCode})`); lines.push(`### ${signalName}`); lines.push(''); lines.push(`GET \`/vehicles/{vehicleId}/signals/${signalCode}\``); lines.push(''); if (description) { lines.push(description); lines.push(''); } if (bodySchema) { const properties = bodySchema.properties || {}; const required = bodySchema.required || []; lines.push(''); lines.push(' '); if (Object.keys(properties).length > 0) { lines.push(...handleNestedProperties(properties, required, ' ')); } if (bodySchema.example !== undefined) { lines.push(''); lines.push('```json Example'); lines.push(JSON.stringify(bodySchema.example, null, 2)); lines.push('```'); } lines.push(' '); lines.push(''); } lines.push(''); }); const fileName = `${groupName.toLowerCase()}.mdx`; const outPath = path.resolve(outputDir, fileName); if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true }); // Remove any existing file with different casing fs.readdirSync(outputDir).forEach(f => { if (f.toLowerCase() === fileName && f !== fileName) { try { fs.unlinkSync(path.join(outputDir, f)); console.log(`Removed old file with different case: ${f}`); } catch (err) { console.error(`Error removing ${f}:`, err); } } }); fs.writeFileSync(outPath, lines.join('\n'), 'utf8'); console.log(`✅ Wrote ${outPath}`); } // --------------------------------------------------------------------------- // Snippets // --------------------------------------------------------------------------- function writeSnippet(groups, outputFile) { const lines = Object.keys(groups) .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())) .map(group => `- [${group}](/api-reference/signals/${group.toLowerCase()})`); lines.push(''); const dir = path.dirname(outputFile); if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(outputFile, lines.join('\n'), 'utf8'); } // --------------------------------------------------------------------------- // docs.json // --------------------------------------------------------------------------- function updateDocsJson(groupNames) { const docs = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, 'utf8')); let found = false; (docs.navigation?.tabs || []).forEach(tab => { (tab.groups || []).forEach(groupObj => { if (groupObj.group === 'Smartcar Signals & Attributes' && Array.isArray(groupObj.pages)) { const newPages = groupNames.map(name => `api-reference/signals/${name}`); const pageSet = new Set(groupObj.pages.map(p => p.toLowerCase())); newPages.forEach(p => pageSet.add(p)); const allPages = Array.from(pageSet); const hasSchema = allPages.some(p => p.toLowerCase() === SCHEMA_NAV_PATH); let rest = allPages .filter(p => p.toLowerCase() !== SCHEMA_NAV_PATH) .sort((a, b) => a.split('/').pop().localeCompare(b.split('/').pop())); groupObj.pages = hasSchema ? [SCHEMA_NAV_PATH, ...rest] : rest; found = true; } }); }); if (found) { fs.writeFileSync(DOCS_JSON_PATH, JSON.stringify(docs, null, 2) + '\n', 'utf8'); console.log('✅ Updated Smartcar Signals & Attributes pages in docs.json'); } else { console.warn('⚠️ Could not find Smartcar Signals & Attributes group in docs.json'); } } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- function main() { console.log(`📥 Reading: ${VEHICLE_SIGNALS_PATH}`); const spec = loadYaml(VEHICLE_SIGNALS_PATH); const paths = spec.paths || {}; // Extract and group signals by their first tag const groups = {}; Object.entries(paths).forEach(([pathKey, pathItem]) => { const op = pathItem.get; if (!op) return; const tag = (op.tags || [])[0]; if (!tag) return; const signalCode = pathKey.split('/signals/')[1]; if (!signalCode) return; const responseSchema = op.responses?.['200']?.content?.['application/json']?.schema; const attrsProps = responseSchema?.properties?.attributes?.properties; const signalName = attrsProps?.name?.example || signalCode; const bodySchema = attrsProps?.body || null; const description = bodySchema?.description || ''; if (!groups[tag]) groups[tag] = []; groups[tag].push({ signalCode, signalName, description, bodySchema }); }); // Write per-group MDX files Object.entries(groups).forEach(([groupName, signals]) => { writeGroupMdx(groupName, signals, OUTPUT_DIR); }); // Write snippets writeSnippet(groups, path.resolve(SNIPPETS_DIR, 'signals.mdx')); // Update docs.json nav const groupNames = Object.keys(groups).map(g => g.toLowerCase()); updateDocsJson(groupNames); console.log(`\n✅ MDX files generated for ${Object.keys(groups).length} groups in /api-reference/signals/`); } main();

Mode	Description
live	Launches Connect in live mode allowing a user to log in with a real connected services account.
simulated	Launches Connect in simulated mode allowing developers to connect to vehicles created on Dashboard via the Simulator.

Introduction

Launching Connect

Reauthentication

Vehicle Owner Actions

Advanced Configuration

Documentation Index