/** * API Variable core. * * Backs the `Api` state-machine input type: a variable whose value is pulled * directly from a URL on an interval, like a normal API caller. * * This module is deliberately framework-agnostic and dependency-free so the * exact same file can be dropped into the editor and every framework runtime * (React / Vue / Svelte / Solid / Angular / RN / Vanilla). * * Security model: * - https-only by default, credentials-in-URL rejected, private/loopback/ * link-local hosts blocked (anti-SSRF). * - hard timeout + response-size cap, one in-flight request at a time. * - secrets are flagged and can be redacted before a project is exported. */ export type ApiHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; export type ApiAuthType = 'none' | 'bearer' | 'basic' | 'header' | 'query'; export type ApiResultType = 'auto' | 'number' | 'string' | 'boolean' | 'array'; /** A single query param or header row. */ export interface ApiKeyValue { id: string; key: string; value: string; /** Masked in the UI and flagged on export. */ secret?: boolean; enabled?: boolean; } export interface ApiAuthConfig { type: ApiAuthType; /** bearer token */ token?: string; /** basic auth */ username?: string; password?: string; /** for 'header' | 'query' — the name to send the credential under */ keyName?: string; secret?: boolean; } export interface ApiVariableConfig { url: string; method?: ApiHttpMethod; query?: ApiKeyValue[]; headers?: ApiKeyValue[]; /** Raw request body (JSON string) for POST/PUT/PATCH. */ body?: string; auth?: ApiAuthConfig; /** Dot/bracket path into the JSON response, e.g. `$.data.items[0].price`. Empty = whole payload. */ path?: string; resultType?: ApiResultType; /** Poll interval in ms. 0/undefined = manual refresh only. */ intervalMs?: number; /** Request timeout in ms (default 10_000). */ timeoutMs?: number; /** Start polling when the project loads/plays (default true). */ startOnLoad?: boolean; } export interface ApiFetchOutcome { ok: boolean; status?: number; /** Parsed payload. */ data?: unknown; /** Value after path + coercion, i.e. what the variable actually receives. */ value?: unknown; error?: string; durationMs: number; fetchedAt?: number; } export interface ApiUrlCheck { ok: boolean; error?: string; url?: URL; } export const API_MIN_INTERVAL_MS = 1000; export const API_DEFAULT_TIMEOUT_MS = 10_000; export const API_MAX_RESPONSE_BYTES = 1_000_000; // 1 MB /** Injectable fetch so the editor can use the native Tauri transport (no CORS). */ export type ApiFetchLike = (input: string, init?: any) => Promise; function parseIpv4Parts(host: string): number[] | null { const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host); if (!m) return null; const parts = [m[1], m[2], m[3], m[4]].map(p => Number(p)); if (parts.some(p => Number.isNaN(p) || p > 255)) return null; return parts; } /** Loopback / RFC1918 / link-local / CGNAT / metadata endpoints. */ export function isPrivateHost(hostname: string): boolean { const host = (hostname || '').trim().toLowerCase().replace(/^\[|\]$/g, ''); if (!host) return true; if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local')) return true; if (host === '::1' || host === '0.0.0.0' || host === '::' ) return true; if (host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80')) { // IPv6 unique-local / link-local if (/^f[cd][0-9a-f]{2}:/.test(host) || host.startsWith('fe80:')) return true; } const parts = parseIpv4Parts(host); if (!parts) return false; const [a, b] = parts; if (a === 127 || a === 0 || a === 10) return true; if (a === 169 && b === 254) return true; // link-local + cloud metadata if (a === 172 && b >= 16 && b <= 31) return true; if (a === 192 && b === 168) return true; if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT return false; } /** * Validate a user-supplied API URL. Blocks dangerous schemes, embedded * credentials and internal hosts unless explicitly allowed. */ export function assertSafeApiUrl(url: string, options: { allowHttp?: boolean; allowPrivate?: boolean } = {}): ApiUrlCheck { const raw = (url || '').trim(); if (!raw) return { ok: false, error: 'URL is required' }; if (/^(?:javascript|vbscript|data|file|blob):/i.test(raw)) { return { ok: false, error: 'Unsupported URL scheme' }; } let parsed: URL; try { parsed = new URL(raw); } catch { return { ok: false, error: 'Invalid URL (include https://)' }; } if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') { return { ok: false, error: 'Only https:// URLs are allowed' }; } if (parsed.protocol === 'http:' && !options.allowHttp) { return { ok: false, error: 'Only https:// URLs are allowed' }; } if (parsed.username || parsed.password) { return { ok: false, error: 'Do not embed credentials in the URL — use the auth fields' }; } if (!options.allowPrivate && isPrivateHost(parsed.hostname)) { return { ok: false, error: 'Private / local addresses are blocked for security' }; } return { ok: true, url: parsed }; } /** Split a path like `$.a.b[0]["c"]` into tokens. */ export function parseApiPath(path: string): string[] { const trimmed = (path || '').trim(); if (!trimmed || trimmed === '$') return []; const withoutRoot = trimmed.startsWith('$') ? trimmed.slice(1) : trimmed; const tokens: string[] = []; const re = /\[\s*(?:"([^"]*)"|'([^']*)'|([^\]]*))\s*\]|([^.[\]]+)/g; let match: RegExpExecArray | null; while ((match = re.exec(withoutRoot)) !== null) { const token = match[1] ?? match[2] ?? match[3] ?? match[4]; if (token !== undefined && token !== '') tokens.push(String(token).trim()); } return tokens; } /** Resolve a dot/bracket path against parsed JSON. Returns undefined when missing. */ export function resolveJsonPath(data: unknown, path: string): unknown { const tokens = parseApiPath(path); let current: any = data; for (const token of tokens) { if (current === null || current === undefined) return undefined; if (Array.isArray(current)) { // Support `items.id` meaning "pluck field from every row". if (!/^\d+$/.test(token)) { const plucked = current .map(row => (row && typeof row === 'object' ? (row as any)[token] : undefined)) .filter(v => v !== undefined); if (plucked.length > 0) { current = plucked; continue; } } } current = current[token]; } return current; } /** Coerce a raw value into the shape the variable should expose. */ export function coerceApiValue(raw: unknown, resultType: ApiResultType = 'auto'): unknown { const unwrap = (v: unknown): unknown => { if (v && typeof v === 'object' && !Array.isArray(v) && 'value' in (v as any)) { return (v as any).value; } return v; }; const value = unwrap(raw); switch (resultType) { case 'number': { if (typeof value === 'number') return value; if (typeof value === 'boolean') return value ? 1 : 0; const n = Number(value); return Number.isFinite(n) ? n : 0; } case 'string': if (value === null || value === undefined) return ''; if (typeof value === 'object') return JSON.stringify(value); return String(value); case 'boolean': if (typeof value === 'boolean') return value; if (typeof value === 'number') return value !== 0; if (typeof value === 'string') return /^(?:true|1|yes|on)$/i.test(value.trim()); return Boolean(value); case 'array': if (Array.isArray(value)) return value; if (value === null || value === undefined) return []; return [value]; case 'auto': default: return value === undefined ? null : value; } } /** Map an arbitrary array payload to number[] for NumberArray / chart consumers. */ export function toNumberArray(items: unknown): number[] { if (!Array.isArray(items)) { const single = toNumber(items); return single === null ? [] : [single]; } return items .map(item => toNumber(item)) .filter((n): n is number => n !== null); } function toNumber(item: unknown): number | null { if (typeof item === 'number') return Number.isFinite(item) ? item : null; if (typeof item === 'string') { const n = Number(item.trim()); return Number.isFinite(n) ? n : null; } if (item && typeof item === 'object') { // Pluck the first numeric field from an object row. for (const v of Object.values(item as Record)) { const n = toNumber(v); if (n !== null) return n; } } return null; } /** Full extraction: payload -> path -> coerced value. */ export function extractApiValue(payload: unknown, config: Pick): unknown { const selected = config.path ? resolveJsonPath(payload, config.path) : payload; return coerceApiValue(selected, config.resultType || 'auto'); } /** Build the final request URL, appending enabled query params. */ export function buildApiUrl(config: ApiVariableConfig): { url: string; error?: string } { const check = assertSafeApiUrl(config.url); if (!check.ok || !check.url) return { url: '', error: check.error }; const url = check.url; (config.query || []).forEach(row => { if (row.enabled === false || !row.key) return; url.searchParams.set(row.key, row.value ?? ''); }); const auth = config.auth; if (auth && auth.type === 'query' && auth.keyName) { url.searchParams.set(auth.keyName, auth.token ?? ''); } return { url: url.toString() }; } /** Build request headers, including any configured auth. */ export function buildApiHeaders(config: ApiVariableConfig): Record { const headers: Record = {}; (config.headers || []).forEach(row => { if (row.enabled === false || !row.key) return; headers[row.key] = row.value ?? ''; }); const auth = config.auth; if (auth) { if (auth.type === 'bearer' && auth.token) { headers['Authorization'] = `Bearer ${auth.token}`; } else if (auth.type === 'basic') { const encoded = safeBtoa(`${auth.username ?? ''}:${auth.password ?? ''}`); headers['Authorization'] = `Basic ${encoded}`; } else if (auth.type === 'header' && auth.keyName) { headers[auth.keyName] = auth.token ?? ''; } } const hasContentType = Object.keys(headers).some(h => h.toLowerCase() === 'content-type'); if (!hasContentType && config.body && config.method && config.method !== 'GET') { headers['Content-Type'] = 'application/json'; } return headers; } const B64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'; /** * Base64 encoder for basic auth. Implemented inline so the module stays free of * Node (`Buffer`) and DOM (`btoa`) dependencies — it runs in every runtime. */ function safeBtoa(input: string): string { try { if (typeof btoa === 'function') return btoa(input); } catch { /* fall through to the manual encoder */ } const utf8 = unescape(encodeURIComponent(input)); let out = ''; for (let i = 0; i < utf8.length; i += 3) { const c1 = utf8.charCodeAt(i); const c2 = utf8.charCodeAt(i + 1); const c3 = utf8.charCodeAt(i + 2); out += B64_CHARS[c1 >> 2]; out += B64_CHARS[((c1 & 3) << 4) | (isNaN(c2) ? 0 : c2 >> 4)]; out += isNaN(c2) ? '=' : B64_CHARS[((c2 & 15) << 2) | (isNaN(c3) ? 0 : c3 >> 6)]; out += isNaN(c3) ? '=' : B64_CHARS[c3 & 63]; } return out; } /** True when any auth/header/query value is flagged as a secret. */ export function hasApiSecrets(config: ApiVariableConfig | undefined | null): boolean { if (!config) return false; const rows = [...(config.query || []), ...(config.headers || [])]; if (rows.some(r => r.secret && r.value)) return true; if (config.auth && (config.auth.secret || config.auth.type !== 'none')) { return Boolean(config.auth.token || config.auth.password); } return false; } /** Names of every Api input in a project that holds a secret value. */ export function findApiInputsWithSecrets(inputs: any[] | undefined | null): string[] { return (inputs || []) .filter(input => input?.value?.type === 'Api' && hasApiSecrets(input.value.api)) .map(input => input.name || input.id); } const REDACTED = '••••••••'; /** Mask secret values (safe for logs, UI peek and export warnings). */ export function redactApiConfig(config: ApiVariableConfig): ApiVariableConfig { const mask = (rows?: ApiKeyValue[]): ApiKeyValue[] | undefined => rows?.map(r => (r.secret && r.value ? { ...r, value: REDACTED } : { ...r })); return { ...config, query: mask(config.query), headers: mask(config.headers), auth: config.auth ? { ...config.auth, token: config.auth.token ? REDACTED : config.auth.token, password: config.auth.password ? REDACTED : config.auth.password, } : config.auth, }; } /** * Replace secret values with an env placeholder before export so credentials * never leave the machine. The runtime resolves `__EXODE_SECRET___` from * `globalThis.__EXODE_ENV__` when present. */ export function stripApiSecretsForExport(config: ApiVariableConfig): ApiVariableConfig { const strip = (rows?: ApiKeyValue[]): ApiKeyValue[] | undefined => rows?.map(r => (r.secret && r.value ? { ...r, value: secretPlaceholder(r.key || r.id) } : { ...r })); return { ...config, query: strip(config.query), headers: strip(config.headers), auth: config.auth ? { ...config.auth, token: config.auth.token ? secretPlaceholder('AUTH_TOKEN') : config.auth.token, password: config.auth.password ? secretPlaceholder('AUTH_PASSWORD') : config.auth.password, } : config.auth, }; } export function secretPlaceholder(key: string): string { return `__EXODE_SECRET_${String(key).toUpperCase().replace(/[^A-Z0-9]+/g, '_')}__`; } /** Resolve export placeholders from the runtime environment, if provided. */ function resolveSecret(raw: string): string { const m = /^__EXODE_SECRET_(.+)__$/.exec(raw || ''); if (!m) return raw; const env = (globalThis as any).__EXODE_ENV__; if (env && typeof env === 'object' && typeof env[m[1]] === 'string') return env[m[1]]; return raw; } function resolveConfigSecrets(config: ApiVariableConfig): ApiVariableConfig { return { ...config, query: config.query?.map(r => ({ ...r, value: resolveSecret(r.value) })), headers: config.headers?.map(r => ({ ...r, value: resolveSecret(r.value) })), auth: config.auth ? { ...config.auth, token: config.auth.token ? resolveSecret(config.auth.token) : config.auth.token, password: config.auth.password ? resolveSecret(config.auth.password) : config.auth.password, } : config.auth, }; } /** Clamp a user-entered interval to something that cannot hammer an API. */ export function clampApiInterval(intervalMs?: number): number { if (!intervalMs || intervalMs <= 0) return 0; return Math.max(API_MIN_INTERVAL_MS, Math.floor(intervalMs)); } export interface ApiPollerCallbacks { onValue?: (value: unknown, outcome: ApiFetchOutcome) => void; onStatus?: (outcome: ApiFetchOutcome) => void; } /** * Fetches an Api variable's URL and reports the resolved value on an interval. * * One request in flight at a time, hard timeout, size cap, and exponential * backoff on failures. Pauses automatically while the tab is hidden. */ export class ApiVariablePoller { private config: ApiVariableConfig; private timer: ReturnType | null = null; private controller: AbortController | null = null; private stopped = true; private inFlight = false; private failureCount = 0; private fetchImpl: ApiFetchLike; private callbacks: ApiPollerCallbacks; private hiddenHandler?: () => void; /** Timestamp of the last successful fetch. */ lastSuccessAt?: number; constructor( config: ApiVariableConfig, callbacks: ApiPollerCallbacks = {}, fetchImpl?: ApiFetchLike, ) { this.config = config; this.callbacks = callbacks; this.fetchImpl = fetchImpl || ((input: string, init?: any) => { const f = (globalThis as any).fetch; if (typeof f !== 'function') { return Promise.reject(new Error('fetch is not available in this environment')); } return f(input, init); }); } getConfig(): ApiVariableConfig { return this.config; } setConfig(config: ApiVariableConfig) { this.config = config; if (!this.stopped) { this.restart(); } } start() { if (!this.stopped) return; this.stopped = false; this.failureCount = 0; this.attachVisibilityHandler(); this.schedule(0); } stop() { this.stopped = true; if (this.timer !== null) { clearTimeout(this.timer); this.timer = null; } this.detachVisibilityHandler(); if (this.controller) { try { this.controller.abort(); } catch { /* noop */ } this.controller = null; } } restart() { const wasRunning = !this.stopped; this.stop(); if (wasRunning) this.start(); } /** One-shot fetch (used by the editor's Refresh button and manual mode). */ async refresh(): Promise { return this.fetchOnce(); } private attachVisibilityHandler() { const doc = (globalThis as any).document; if (!doc || typeof doc.addEventListener !== 'function' || this.hiddenHandler) return; this.hiddenHandler = () => { if (doc.hidden) { if (this.timer !== null) { clearTimeout(this.timer); this.timer = null; } } else if (!this.stopped) { this.schedule(0); } }; doc.addEventListener('visibilitychange', this.hiddenHandler); } private detachVisibilityHandler() { const doc = (globalThis as any).document; if (this.hiddenHandler && doc && typeof doc.removeEventListener === 'function') { doc.removeEventListener('visibilitychange', this.hiddenHandler); } this.hiddenHandler = undefined; } private schedule(delayMs: number) { if (this.stopped) return; if (this.timer !== null) clearTimeout(this.timer); this.timer = setTimeout(() => { this.timer = null; void this.tick(); }, delayMs); } private nextDelay(base: number): number { if (base <= 0) return 0; if (this.failureCount === 0) return base; // Exponential backoff, capped at 60s. return Math.min(base * Math.pow(2, Math.min(this.failureCount, 5)), 60_000); } private async tick() { if (this.stopped) return; const base = clampApiInterval(this.config.intervalMs); await this.fetchOnce(); if (this.stopped) return; if (base > 0) { this.schedule(this.nextDelay(base)); } } private async fetchOnce(): Promise { if (this.inFlight) { return { ok: false, error: 'Request already in flight', durationMs: 0 }; } this.inFlight = true; const started = Date.now(); const controller = new AbortController(); this.controller = controller; const timeout = Math.max(500, this.config.timeoutMs || API_DEFAULT_TIMEOUT_MS); const timeoutId = setTimeout(() => { try { controller.abort(); } catch { /* noop */ } }, timeout); try { const { url, error } = buildApiUrl(resolveConfigSecrets(this.config)); if (error || !url) { return this.finish({ ok: false, error: error || 'Invalid URL', durationMs: Date.now() - started }); } const method = this.config.method || 'GET'; const init: any = { method, headers: buildApiHeaders(resolveConfigSecrets(this.config)), signal: controller.signal, }; if (this.config.body && method !== 'GET') { init.body = this.config.body; } const response = await this.fetchImpl(url, init); const status: number | undefined = response?.status; if (response && response.ok === false) { return this.finish({ ok: false, status, error: `HTTP ${status ?? 'error'}`, durationMs: Date.now() - started, }); } const text = await this.readBodyCapped(response); let payload: unknown = text; if (text) { try { payload = JSON.parse(text); } catch { payload = text; // plain-text endpoints are valid too } } else { payload = null; } const value = extractApiValue(payload, this.config); const outcome: ApiFetchOutcome = { ok: true, status, data: payload, value, durationMs: Date.now() - started, fetchedAt: Date.now(), }; this.failureCount = 0; this.lastSuccessAt = outcome.fetchedAt; this.callbacks.onValue?.(value, outcome); this.callbacks.onStatus?.(outcome); return outcome; } catch (err: any) { const aborted = err?.name === 'AbortError'; return this.finish({ ok: false, error: aborted ? 'Request timed out' : (err?.message || 'Request failed'), durationMs: Date.now() - started, }); } finally { clearTimeout(timeoutId); if (this.controller === controller) this.controller = null; this.inFlight = false; } } private finish(outcome: ApiFetchOutcome): ApiFetchOutcome { this.failureCount += 1; this.callbacks.onStatus?.(outcome); return outcome; } private async readBodyCapped(response: any): Promise { const declared = Number(response?.headers?.get?.('content-length')); if (Number.isFinite(declared) && declared > API_MAX_RESPONSE_BYTES) { throw new Error('Response too large'); } if (typeof response.text === 'function') { const text = await response.text(); if (typeof text === 'string' && text.length > API_MAX_RESPONSE_BYTES) { throw new Error('Response too large'); } return text; } // Tauri's response shape exposes json()/arrayBuffer() as well. if (typeof response.json === 'function') { try { const json = await response.json(); const text = JSON.stringify(json); if (text.length > API_MAX_RESPONSE_BYTES) throw new Error('Response too large'); return text; } catch (err: any) { if (err?.message === 'Response too large') throw err; return ''; } } return ''; } } /** Default config for a freshly created API variable. */ export function createDefaultApiConfig(): ApiVariableConfig { return { url: '', method: 'GET', query: [], headers: [], auth: { type: 'none' }, path: '', resultType: 'auto', intervalMs: 5000, timeoutMs: API_DEFAULT_TIMEOUT_MS, startOnLoad: true, }; } /** * Working sample used when a new API variable is created, so it shows a live * value immediately. This endpoint needs no auth, allows any origin, and * returns a different value on every request. */ export function createSampleApiConfig(): ApiVariableConfig { return { ...createDefaultApiConfig(), url: randomUserApiUrl(), path: '$.results[0].name.first', resultType: 'string', intervalMs: 5000, }; } function randomUserApiUrl(): string { return 'https://randomuser.me/api/'; } /** Alternate sample showing list handling: `$.products` is an array of rows. */ export function createSampleArrayApiConfig(): ApiVariableConfig { return { ...createDefaultApiConfig(), url: 'https://dummyjson.com/products?limit=5', path: '$.products', resultType: 'array', intervalMs: 5000, }; } /** Read an Api config off a state-machine input, tolerating older shapes. */ export function getApiConfig(input: any): ApiVariableConfig | null { const value = input?.value; if (!value || value.type !== 'Api') return null; const config = value.api || {}; return { ...createDefaultApiConfig(), ...config, url: config.url || '', }; }