@safeaccess/inline 0.1.1

package/src/accessors/formats/array-accessor.ts

@@ -0,0 +1,45 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+
+/**
+ * Accessor for plain objects and arrays.
+ *
+ * Accepts a plain object or array directly. No string parsing is involved.
+ *
+ * @example
+ * const accessor = new ArrayAccessor(parser).from({ key: 'value' });
+ * accessor.get('key'); // 'value'
+ */
+export class ArrayAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a plain object or array.
+     *
+     * @param data - Object or array input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is neither an object nor an array.
+     * @throws {SecurityException} When data contains forbidden keys.
+     *
+     * @example
+     * accessor.from({ name: 'Alice' });
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'object' || data === null) {
+            /* Stryker disable StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(
+                `ArrayAccessor expects an object or array, got ${typeof data}`,
+            );
+            /* Stryker restore StringLiteral */
+        }
+
+        const resolved: Record<string, unknown> = Array.isArray(data)
+            ? Object.fromEntries(data.map((v, i) => [String(i), v]))
+            : (data as Record<string, unknown>);
+
+        return this.ingest(resolved);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        return raw as Record<string, unknown>;
+    }
+}

package/src/accessors/formats/env-accessor.ts

@@ -0,0 +1,79 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+
+/**
+ * Accessor for dotenv-formatted strings.
+ *
+ * Parses KEY=VALUE lines, skipping comments (#) and blank lines.
+ * Strips surrounding single and double quotes from values.
+ *
+ * @example
+ * const accessor = new EnvAccessor(parser).from('DB_HOST=localhost\nDEBUG=true');
+ * accessor.get('DB_HOST'); // 'localhost'
+ */
+export class EnvAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a dotenv-formatted string.
+     *
+     * @param data - Dotenv string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('APP_ENV=production\nPORT=3000');
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'string') {
+            /* Stryker disable next-line StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(
+                `EnvAccessor expects an ENV string, got ${typeof data}`,
+            );
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+
+        const result: Record<string, unknown> = {};
+
+        for (const rawLine of raw.split('\n')) {
+            /* Stryker disable next-line MethodExpression -- trim() on rawLine: whitespace-only lines still skip via empty check below */
+            const line = rawLine.trim();
+
+            /* Stryker disable next-line ConditionalExpression,LogicalOperator,StringLiteral,MethodExpression -- equivalent: blank lines not matching = are caught by eqPos === -1 guard; comment-skipping still works */
+            if (line === '' || line.startsWith('#')) {
+                continue;
+            }
+
+            const eqPos = line.indexOf('=');
+            /* Stryker disable next-line ConditionalExpression,UnaryOperator,BlockStatement -- equivalent: lines without = produce no usable key=value pair */
+            if (eqPos === -1) {
+                continue;
+            }
+
+            const key = line.slice(0, eqPos).trim();
+            let value = line.slice(eqPos + 1).trim();
+
+            // Strip surrounding quotes
+            if (
+                (value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))
+            ) {
+                value = value.slice(1, -1);
+            }
+
+            result[key] = value;
+        }
+
+        return result;
+    }
+}

package/src/accessors/formats/ini-accessor.ts

@@ -0,0 +1,124 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+
+/**
+ * Accessor for INI-formatted strings.
+ *
+ * Parses sections (e.g. `[section]`) as nested keys.
+ * Type inference: numeric strings become numbers, `true`/`false` become booleans.
+ *
+ * @example
+ * const accessor = new IniAccessor(parser).from('[db]\nhost=localhost\nport=5432');
+ * accessor.get('db.host'); // 'localhost'
+ */
+export class IniAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from an INI-formatted string.
+     *
+     * @param data - INI string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('key=value\n[section]\nname=Alice');
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'string') {
+            /* Stryker disable next-line StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(
+                `IniAccessor expects an INI string, got ${typeof data}`,
+            );
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+
+        return this.parseIni(raw);
+    }
+
+    /**
+     * Parse an INI string into a nested record.
+     *
+     * @param input - Raw INI content.
+     * @returns Parsed key-value structure.
+     */
+    private parseIni(input: string): Record<string, unknown> {
+        const result: Record<string, unknown> = {};
+        let currentSection: string | null = null;
+
+        for (const rawLine of input.split('\n')) {
+            /* Stryker disable next-line MethodExpression -- equivalent: untrimmed leading whitespace on keys/values handled by subsequent trim() calls */
+            const line = rawLine.trim();
+
+            /* Stryker disable next-line ConditionalExpression,LogicalOperator,StringLiteral,MethodExpression,BlockStatement -- fallthrough: blank/comment lines without = still skip via eqPos === -1 */
+            if (line === '' || line.startsWith('#') || line.startsWith(';')) {
+                continue;
+            }
+
+            // Section header
+            const sectionMatch = /^\[([^\]]+)\]/.exec(line);
+            if (sectionMatch !== null) {
+                currentSection = sectionMatch[1] as string;
+                if (!Object.prototype.hasOwnProperty.call(result, currentSection)) {
+                    result[currentSection] = {};
+                }
+                continue;
+            }
+
+            // Key=Value
+            const eqPos = line.indexOf('=');
+            /* Stryker disable next-line ConditionalExpression,BlockStatement -- equivalent: lines without = produce no usable key=value pair */
+            if (eqPos === -1) {
+                continue;
+            }
+
+            const key = line.slice(0, eqPos).trim();
+            const rawValue = line.slice(eqPos + 1).trim();
+            const value = this.castIniValue(rawValue);
+
+            if (currentSection !== null) {
+                (result[currentSection] as Record<string, unknown>)[key] = value;
+            } else {
+                result[key] = value;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Cast an INI string value to its native type.
+     *
+     * @param value - Raw string value from the INI file.
+     * @returns Typed value (boolean, null, number, or string).
+     */
+    private castIniValue(value: string): unknown {
+        if (value === 'true' || value === 'yes' || value === 'on') return true;
+        if (value === 'false' || value === 'no' || value === 'off' || value === 'none')
+            return false;
+        if (value === 'null' || value === '') return null;
+
+        // Strip surrounding quotes
+        if (
+            (value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))
+        ) {
+            return value.slice(1, -1);
+        }
+
+        if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+        if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+
+        return value;
+    }
+}

package/src/accessors/formats/json-accessor.ts

@@ -0,0 +1,66 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+
+/**
+ * Accessor for JSON-encoded strings.
+ *
+ * Decodes JSON via `JSON.parse()`. Validates payload size before parsing.
+ *
+ * @example
+ * const accessor = new JsonAccessor(parser).from('{"key":"value"}');
+ * accessor.get('key'); // 'value'
+ */
+export class JsonAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a JSON string.
+     *
+     * @param data - JSON string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string or JSON is malformed.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('{"name":"Alice"}');
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'string') {
+            /* Stryker disable StringLiteral -- error message content is cosmetic; mutation produces empty string which is still an InvalidFormatException */
+            throw new InvalidFormatException(
+                `JsonAccessor expects a JSON string, got ${typeof data}`,
+            );
+            /* Stryker restore StringLiteral */
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+
+        let decoded: unknown;
+        try {
+            decoded = JSON.parse(raw);
+        } catch (err) {
+            /* Stryker disable StringLiteral,ObjectLiteral -- error message cosmetic; cause object content not observable via public API */
+            /* c8 ignore start */
+            throw new InvalidFormatException(
+                `JsonAccessor failed to parse JSON: ${err instanceof Error ? err.message : String(err)}`,
+                { cause: err instanceof Error ? err : undefined },
+            );
+            /* c8 ignore stop */
+            /* Stryker restore StringLiteral,ObjectLiteral */
+        }
+
+        if (typeof decoded !== 'object' || decoded === null) {
+            return {};
+        }
+
+        return decoded as Record<string, unknown>;
+    }
+}

package/src/accessors/formats/ndjson-accessor.ts

@@ -0,0 +1,82 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+
+/**
+ * Accessor for Newline-Delimited JSON (NDJSON) strings.
+ *
+ * Parses each non-empty line as a standalone JSON object,
+ * producing an indexed record of parsed entries.
+ *
+ * @example
+ * const ndjson = '{"id":1}\n{"id":2}';
+ * const accessor = new NdjsonAccessor(parser).from(ndjson);
+ * accessor.get('0.id'); // 1
+ */
+export class NdjsonAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from an NDJSON string.
+     *
+     * @param data - NDJSON string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string or any line is malformed.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('{"name":"Alice"}\n{"name":"Bob"}');
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'string') {
+            /* Stryker disable StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(
+                `NdjsonAccessor expects an NDJSON string, got ${typeof data}`,
+            );
+            /* Stryker restore StringLiteral */
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+
+        const result: Record<string, unknown> = {};
+        const allLines = raw.split('\n');
+        const nonEmptyLines: Array<{ line: string; originalLine: number }> = [];
+
+        /* Stryker disable next-line EqualityOperator -- equivalent: extra undefined allLines[length] entry is safely handled by ?? '' */
+        for (let idx = 0; idx < allLines.length; idx++) {
+            /* Stryker disable next-line StringLiteral -- NoCoverage: allLines[idx] is always defined within valid loop bounds */
+            /* c8 ignore next */
+            const trimmed = (allLines[idx] ?? '').trim();
+            if (trimmed !== '') {
+                nonEmptyLines.push({ line: trimmed, originalLine: idx + 1 });
+            }
+        }
+
+        /* Stryker disable next-line ConditionalExpression,BlockStatement -- equivalent: empty nonEmptyLines causes loop to run 0 iterations and returns {} naturally */
+        if (nonEmptyLines.length === 0) {
+            return {};
+        }
+
+        for (let i = 0; i < nonEmptyLines.length; i++) {
+            const entry = nonEmptyLines[i]!;
+            let decoded: unknown;
+            try {
+                decoded = JSON.parse(entry.line);
+            } catch {
+                throw new InvalidFormatException(
+                    `NdjsonAccessor failed to parse line ${entry.originalLine}: ${entry.line}`,
+                );
+            }
+            result[String(i)] = decoded;
+        }
+
+        return result;
+    }
+}

package/src/accessors/formats/object-accessor.ts

@@ -0,0 +1,100 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+import { SecurityException } from '../../exceptions/security-exception.js';
+
+/**
+ * Accessor for JavaScript objects, converting them to plain records recursively.
+ *
+ * Handles nested objects and arrays of objects without JSON roundtrip.
+ * Respects the configured max depth to prevent DoS from deeply nested structures.
+ *
+ * @example
+ * const obj = { user: { name: 'Alice' } };
+ * const accessor = new ObjectAccessor(parser).from(obj);
+ * accessor.get('user.name'); // 'Alice'
+ */
+export class ObjectAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a JavaScript object.
+     *
+     * @param data - Object input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not an object.
+     * @throws {SecurityException} When data contains forbidden keys or exceeds depth limit.
+     *
+     * @example
+     * accessor.from({ name: 'Alice', age: 30 });
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+            throw new InvalidFormatException(
+                `ObjectAccessor expects an object, got ${Array.isArray(data) ? 'array' : typeof data}`,
+            );
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        return this.objectToRecord(raw as Record<string, unknown>, 0);
+    }
+
+    /**
+     * Recursively convert a nested object into a plain record.
+     *
+     * @param value - Object to convert.
+     * @param depth - Current recursion depth.
+     * @returns Converted record.
+     *
+     * @throws {SecurityException} When recursion depth exceeds the configured maximum.
+     */
+    private objectToRecord(value: Record<string, unknown>, depth: number): Record<string, unknown> {
+        const maxDepth = this.parser.getMaxDepth();
+
+        if (depth > maxDepth) {
+            throw new SecurityException(`Object depth ${depth} exceeds maximum of ${maxDepth}.`);
+        }
+
+        const result: Record<string, unknown> = {};
+
+        for (const [key, val] of Object.entries(value)) {
+            if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+                result[key] = this.objectToRecord(val as Record<string, unknown>, depth + 1);
+            } else if (Array.isArray(val)) {
+                result[key] = this.convertArrayValues(val, depth + 1);
+            } else {
+                result[key] = val;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Recursively convert nested arrays containing objects.
+     *
+     * @param array - Array to process.
+     * @param depth - Current recursion depth.
+     * @returns Array with all objects converted.
+     *
+     * @throws {SecurityException} When recursion depth exceeds the configured maximum.
+     */
+    private convertArrayValues(array: unknown[], depth: number): unknown[] {
+        const maxDepth = this.parser.getMaxDepth();
+
+        if (depth > maxDepth) {
+            /* Stryker disable next-line StringLiteral -- error message content is cosmetic; test asserts exception type only */
+            throw new SecurityException(`Object depth ${depth} exceeds maximum of ${maxDepth}.`);
+        }
+
+        return array.map((val) => {
+            if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+                return this.objectToRecord(val as Record<string, unknown>, depth + 1);
+            } else if (Array.isArray(val)) {
+                return this.convertArrayValues(val, depth + 1);
+            }
+            return val;
+        });
+    }
+}

package/src/accessors/formats/xml-accessor.ts

@@ -0,0 +1,58 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+import { SecurityException } from '../../exceptions/security-exception.js';
+import { XmlParser } from '../../parser/xml-parser.js';
+
+/**
+ * Accessor for XML strings.
+ *
+ * Parses XML using the DOM parser available in the current environment.
+ * Blocks DOCTYPE declarations to prevent XXE attacks.
+ *
+ * @example
+ * const accessor = new XmlAccessor(parser).from('<root><key>value</key></root>');
+ * accessor.get('key'); // 'value'
+ */
+export class XmlAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from an XML string.
+     *
+     * @param data - XML string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string.
+     * @throws {SecurityException} When DOCTYPE declaration is detected.
+     *
+     * @example
+     * accessor.from('<root><name>Alice</name></root>');
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'string') {
+            throw new InvalidFormatException(
+                /* Stryker disable next-line StringLiteral -- error message content is cosmetic */
+                `XmlAccessor expects an XML string, got ${typeof data}`,
+            );
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+
+        // Reject DOCTYPE to prevent XXE
+        if (/<!DOCTYPE/i.test(raw)) {
+            /* Stryker disable next-line StringLiteral -- error message content is the security message, tested functionally */
+            throw new SecurityException('XML DOCTYPE declarations are not allowed.');
+        }
+
+        // Pass getMaxKeys() as the element-count cap: each XML opening tag maps to at most
+        // one output key, so maxKeys is a sound upper bound for the ReDoS guard.
+        return new XmlParser(this.parser.getMaxDepth(), this.parser.getMaxKeys()).parse(raw);
+    }
+}

package/src/accessors/formats/yaml-accessor.ts

@@ -0,0 +1,52 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+import { YamlParser } from '../../parser/yaml-parser.js';
+
+/**
+ * Accessor for YAML-encoded strings.
+ *
+ * Uses the internal YamlParser for safe YAML parsing without
+ * depending on external YAML libraries. Tags, anchors, aliases, and
+ * merge keys are blocked as unsafe constructs.
+ *
+ * @example
+ * const accessor = new YamlAccessor(parser).from('key: value\nnested:\n  a: 1');
+ * accessor.get('nested.a'); // 1
+ */
+export class YamlAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a YAML string.
+     *
+     * @param data - YAML string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string or YAML is malformed.
+     * @throws {YamlParseException} When unsafe YAML constructs are present.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('name: Alice\nage: 30');
+     */
+    from(data: unknown): this {
+        if (typeof data !== 'string') {
+            /* Stryker disable StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(
+                `YamlAccessor expects a YAML string, got ${typeof data}`,
+            );
+            /* Stryker restore StringLiteral */
+        }
+
+        return this.ingest(data);
+    }
+
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown> {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+
+        return new YamlParser().parse(raw);
+    }
+}

package/src/contracts/accessors-interface.ts

@@ -0,0 +1,12 @@
+import type { ReadableAccessorsInterface } from './readable-accessors-interface.js';
+import type { WritableAccessorsInterface } from './writable-accessors-interface.js';
+import type { FactoryAccessorsInterface } from './factory-accessors-interface.js';
+
+/**
+ * Unified contract combining read, write, and factory capabilities.
+ *
+ * Marker interface that aggregates all accessor responsibilities into
+ * a single type, used as the base contract for AbstractAccessor.
+ */
+export interface AccessorsInterface
+    extends ReadableAccessorsInterface, WritableAccessorsInterface, FactoryAccessorsInterface {}

package/src/contracts/factory-accessors-interface.ts

@@ -0,0 +1,16 @@
+/**
+ * Contract for creating accessor instances from raw input.
+ *
+ * Note: this `from(data)` is the per-accessor hydrator, not
+ * {@link Inline.from} which selects an accessor by TypeFormat.
+ */
+export interface FactoryAccessorsInterface {
+    /**
+     * Hydrate the accessor from raw input data.
+     *
+     * @param data - Raw input in the format expected by the accessor.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the input cannot be parsed.
+     */
+    from(data: unknown): this;
+}

package/src/contracts/parse-integration-interface.ts

@@ -0,0 +1,32 @@
+/**
+ * Contract for custom format detection and parsing integration.
+ *
+ * Enables the {@link AnyAccessor} to accept arbitrary input by delegating
+ * format validation and parsing to a user-provided implementation.
+ *
+ * @example
+ * class CsvIntegration implements ParseIntegrationInterface {
+ *   assertFormat(raw: unknown): boolean { return typeof raw === 'string' && raw.includes(','); }
+ *   parse(raw: unknown): Record<string, unknown> { ... }
+ * }
+ * const accessor = Inline.withParserIntegration(new CsvIntegration()).fromAny(csvString);
+ */
+export interface ParseIntegrationInterface {
+    /**
+     * Determine whether the given raw input is in a supported format.
+     *
+     * @param raw - Raw input data to validate.
+     * @returns `true` if the input can be parsed by this integration.
+     */
+    assertFormat(raw: unknown): boolean;
+
+    /**
+     * Parse raw input data into a normalized plain object.
+     *
+     * Called only after {@link assertFormat} returns `true`.
+     *
+     * @param raw - Raw input data previously validated by {@link assertFormat}.
+     * @returns Parsed data as a nested plain object.
+     */
+    parse(raw: unknown): Record<string, unknown>;
+}