@start9labs/start-sdk 0.4.0-beta.51 → 0.4.0-beta.52

package/base/lib/actions/input/inputSpecTypes.d.ts

@@ -1,47 +1,81 @@
+/**
+ * A record mapping field keys to their {@link ValueSpec} definitions.
+ * This is the root shape of a dynamic form specification — it defines the complete set
+ * of configurable fields for a service or action.
+ */
 export type InputSpec = Record<string, ValueSpec>;
+/**
+ * The discriminator for all supported form field types.
+ */
 export type ValueType = 'text' | 'textarea' | 'number' | 'color' | 'datetime' | 'toggle' | 'select' | 'multiselect' | 'list' | 'object' | 'file' | 'union' | 'hidden';
+/** Union of all concrete form field spec types. Discriminate on the `type` field. */
 export type ValueSpec = ValueSpecOf<ValueType>;
 /** core spec types. These types provide the metadata for performing validations */
 export type ValueSpecOf<T extends ValueType> = T extends "text" ? ValueSpecText : T extends "textarea" ? ValueSpecTextarea : T extends "number" ? ValueSpecNumber : T extends "color" ? ValueSpecColor : T extends "datetime" ? ValueSpecDatetime : T extends "toggle" ? ValueSpecToggle : T extends "select" ? ValueSpecSelect : T extends "multiselect" ? ValueSpecMultiselect : T extends "list" ? ValueSpecList : T extends "object" ? ValueSpecObject : T extends "file" ? ValueSpecFile : T extends "union" ? ValueSpecUnion : T extends "hidden" ? ValueSpecHidden : never;
+/** Spec for a single-line text input field. */
 export type ValueSpecText = {
+    /** Display label for the field. */
     name: string;
+    /** Optional help text displayed below the field. */
     description: string | null;
+    /** Optional warning message displayed to the user. */
     warning: string | null;
     type: 'text';
+    /** Regex patterns used to validate the input value. */
     patterns: Pattern[];
+    /** Minimum character length, or `null` for no minimum. */
     minLength: number | null;
+    /** Maximum character length, or `null` for no maximum. */
     maxLength: number | null;
+    /** Whether the field should obscure input (e.g. for passwords). */
     masked: boolean;
+    /** HTML input mode hint for mobile keyboards. */
     inputmode: 'text' | 'email' | 'tel' | 'url';
+    /** Placeholder text shown when the field is empty. */
     placeholder: string | null;
+    /** Whether the field must have a value. */
     required: boolean;
+    /** Default value, which may be a literal string or a {@link RandomString} generation spec. */
     default: DefaultString | null;
+    /** `false` if editable, or a string message explaining why the field is disabled. */
     disabled: false | string;
+    /** If set, provides a "generate" button that fills the field with a random string matching this spec. */
     generate: null | RandomString;
+    /** Whether the field value cannot be changed after initial configuration. */
     immutable: boolean;
 };
+/** Spec for a multi-line textarea input field. */
 export type ValueSpecTextarea = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'textarea';
+    /** Regex patterns used to validate the input value. */
     patterns: Pattern[];
     placeholder: string | null;
     minLength: number | null;
     maxLength: number | null;
+    /** Minimum number of visible rows. */
     minRows: number;
+    /** Maximum number of visible rows before scrolling. */
     maxRows: number;
     required: boolean;
     default: string | null;
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a numeric input field. */
 export type ValueSpecNumber = {
     type: 'number';
+    /** Minimum allowed value, or `null` for unbounded. */
     min: number | null;
+    /** Maximum allowed value, or `null` for unbounded. */
     max: number | null;
+    /** Whether only whole numbers are accepted. */
     integer: boolean;
+    /** Step increment for the input spinner, or `null` for any precision. */
     step: number | null;
+    /** Display label for the unit (e.g. `"MB"`, `"seconds"`), shown next to the field. */
     units: string | null;
     placeholder: string | null;
     name: string;
@@ -52,51 +86,67 @@ export type ValueSpecNumber = {
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a browser-native color picker field. */
 export type ValueSpecColor = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'color';
     required: boolean;
+    /** Default hex color string (e.g. `"#ff0000"`), or `null`. */
     default: string | null;
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a date, time, or datetime input field. */
 export type ValueSpecDatetime = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'datetime';
     required: boolean;
+    /** Controls which kind of picker is displayed. */
     inputmode: 'date' | 'time' | 'datetime-local';
+    /** Minimum selectable date/time as an ISO string, or `null`. */
     min: string | null;
+    /** Maximum selectable date/time as an ISO string, or `null`. */
     max: string | null;
     default: string | null;
     disabled: false | string;
     immutable: boolean;
 };
+/** Spec for a single-select field displayed as radio buttons in a modal. */
 export type ValueSpecSelect = {
+    /** Map of option keys to display labels. */
     values: Record<string, string>;
     name: string;
     description: string | null;
     warning: string | null;
     type: 'select';
     default: string | null;
+    /** `false` if all enabled, a string disabling the whole field, or an array of disabled option keys. */
     disabled: false | string | string[];
     immutable: boolean;
 };
+/** Spec for a multi-select field displayed as checkboxes in a modal. */
 export type ValueSpecMultiselect = {
+    /** Map of option keys to display labels. */
     values: Record<string, string>;
     name: string;
     description: string | null;
     warning: string | null;
     type: 'multiselect';
+    /** Minimum number of selections required, or `null`. */
     minLength: number | null;
+    /** Maximum number of selections allowed, or `null`. */
     maxLength: number | null;
+    /** `false` if all enabled, a string disabling the whole field, or an array of disabled option keys. */
     disabled: false | string | string[];
+    /** Array of option keys selected by default. */
     default: string[];
     immutable: boolean;
 };
+/** Spec for a boolean toggle (on/off switch). */
 export type ValueSpecToggle = {
     name: string;
     description: string | null;
@@ -106,55 +156,83 @@ export type ValueSpecToggle = {
     disabled: false | string;
     immutable: boolean;
 };
+/**
+ * Spec for a discriminated union field — displays a dropdown for variant selection,
+ * and each variant can have its own nested sub-form.
+ */
 export type ValueSpecUnion = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'union';
+    /** Map of variant keys to their display name and nested form spec. */
     variants: Record<string, {
+        /** Display name for this variant in the dropdown. */
         name: string;
+        /** Nested form spec shown when this variant is selected. */
         spec: InputSpec;
     }>;
+    /** `false` if all enabled, a string disabling the whole field, or an array of disabled variant keys. */
     disabled: false | string | string[];
     default: string | null;
     immutable: boolean;
 };
+/** Spec for a file upload input field. */
 export type ValueSpecFile = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'file';
+    /** Allowed file extensions (e.g. `[".pem", ".crt"]`). */
     extensions: string[];
     required: boolean;
 };
+/** Spec for a collapsible grouping of nested fields (a "sub-form"). */
 export type ValueSpecObject = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'object';
+    /** The nested form spec containing this object's fields. */
     spec: InputSpec;
 };
+/** Spec for a hidden field — not displayed to the user but included in the form data. */
 export type ValueSpecHidden = {
     type: 'hidden';
 };
+/** The two supported list item types. */
 export type ListValueSpecType = 'text' | 'object';
+/** Maps a {@link ListValueSpecType} to its concrete list item spec. */
 export type ListValueSpecOf<T extends ListValueSpecType> = T extends "text" ? ListValueSpecText : T extends "object" ? ListValueSpecObject : never;
+/** A list field spec — union of text-list and object-list variants. */
 export type ValueSpecList = ValueSpecListOf<ListValueSpecType>;
+/**
+ * Spec for a list field — an interface to add, remove, and edit items in an ordered collection.
+ * The `spec` field determines whether list items are text strings or structured objects.
+ */
 export type ValueSpecListOf<T extends ListValueSpecType> = {
     name: string;
     description: string | null;
     warning: string | null;
     type: 'list';
+    /** The item spec — determines whether this is a list of text values or objects. */
     spec: ListValueSpecOf<T>;
+    /** Minimum number of items, or `null` for no minimum. */
     minLength: number | null;
+    /** Maximum number of items, or `null` for no maximum. */
     maxLength: number | null;
     disabled: false | string;
+    /** Default list items to populate on creation. */
     default: string[] | DefaultString[] | Record<string, unknown>[] | readonly string[] | readonly DefaultString[] | readonly Record<string, unknown>[];
 };
+/** A regex validation pattern with a human-readable description of what it enforces. */
 export type Pattern = {
+    /** The regex pattern string (without delimiters). */
     regex: string;
+    /** A user-facing explanation shown when validation fails (e.g. `"Must be a valid email"`). */
     description: string;
 };
+/** Spec for text items within a list field. */
 export type ListValueSpecText = {
     type: 'text';
     patterns: Pattern[];
@@ -165,22 +243,43 @@ export type ListValueSpecText = {
     inputmode: 'text' | 'email' | 'tel' | 'url';
     placeholder: string | null;
 };
+/** Spec for object items within a list field. */
 export type ListValueSpecObject = {
     type: 'object';
+    /** The form spec for each object item. */
     spec: InputSpec;
+    /** Defines how uniqueness is determined among list items. */
     uniqueBy: UniqueBy;
+    /** An expression used to generate the display string for each item in the list summary (e.g. a key path). */
     displayAs: string | null;
 };
+/**
+ * Describes how list items determine uniqueness.
+ * - `null`: no uniqueness constraint
+ * - `string`: unique by a specific field key
+ * - `{ any: UniqueBy[] }`: unique if any of the sub-constraints match
+ * - `{ all: UniqueBy[] }`: unique if all sub-constraints match together
+ */
 export type UniqueBy = null | string | {
     any: readonly UniqueBy[] | UniqueBy[];
 } | {
     all: readonly UniqueBy[] | UniqueBy[];
 };
+/** A default value that is either a literal string or a {@link RandomString} generation spec. */
 export type DefaultString = string | RandomString;
+/** Spec for generating a random string — used for default passwords, API keys, etc. */
 export type RandomString = {
+    /** The character set to draw from (e.g. `"a-zA-Z0-9"`). */
     charset: string;
+    /** The length of the generated string. */
     len: number;
 };
+/**
+ * Type guard that narrows a {@link ValueSpec} to a {@link ValueSpecListOf} of a specific item type.
+ *
+ * @param t - The value spec to check
+ * @param s - The list item type to narrow to (`"text"` or `"object"`)
+ */
 export declare function isValueSpecListOf<S extends ListValueSpecType>(t: ValueSpec, s: S): t is ValueSpecListOf<S> & {
     spec: ListValueSpecOf<S>;
 };

package/base/lib/actions/input/inputSpecTypes.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValueSpecListOf = isValueSpecListOf;
-// sometimes the type checker needs just a little bit of help
+/**
+ * Type guard that narrows a {@link ValueSpec} to a {@link ValueSpecListOf} of a specific item type.
+ *
+ * @param t - The value spec to check
+ * @param s - The list item type to narrow to (`"text"` or `"object"`)
+ */
 function isValueSpecListOf(t, s) {
     return 'spec' in t && t.spec.type === s;
 }

package/base/lib/actions/input/inputSpecTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"inputSpecTypes.js","sourceRoot":"","sources":["../../../../../base/lib/actions/input/inputSpecTypes.ts"],"names":[],"mappings":";;AAkPA,8CAKC;AAND,6DAA6D;AAC7D,SAAgB,iBAAiB,CAC/B,CAAY,EACZ,CAAI;IAEJ,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAA;AACzC,CAAC"}
+{"version":3,"file":"inputSpecTypes.js","sourceRoot":"","sources":["../../../../../base/lib/actions/input/inputSpecTypes.ts"],"names":[],"mappings":";;AAoVA,8CAKC;AAXD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAC/B,CAAY,EACZ,CAAI;IAEJ,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAA;AACzC,CAAC"}

package/base/lib/actions/setupActions.d.ts

@@ -13,9 +13,9 @@ export type GetInput<A extends Record<string, any>> = (options: {
     effects: T.Effects;
     prefill: T.DeepPartial<A> | null;
 }) => Promise<null | void | undefined | T.DeepPartial<A>>;
-export type MaybeFn<T> = T | ((options: {
+export type MaybeFn<T, Opts = {
     effects: T.Effects;
-}) => Promise<T>);
+}> = T | ((options: Opts) => Promise<T>);
 export interface ActionInfo<Id extends T.ActionId, Type extends Record<string, any>> {
     readonly id: Id;
     readonly _INPUT: Type;
@@ -29,7 +29,10 @@ export declare class Action<Id extends T.ActionId, Type extends Record<string, a
     readonly _INPUT: Type;
     private prevInputSpec;
     private constructor();
-    static withInput<Id extends T.ActionId, InputSpecType extends InputSpec<Record<string, any>>>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, 'hasInput'>>, inputSpec: InputSpecType, getInput: GetInput<ExtractInputSpecType<InputSpecType>>, run: Run<ExtractInputSpecType<InputSpecType>>): Action<Id, ExtractInputSpecType<InputSpecType>>;
+    static withInput<Id extends T.ActionId, InputSpecType extends InputSpec<Record<string, any>>>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, 'hasInput'>>, inputSpec: MaybeFn<InputSpecType, {
+        effects: T.Effects;
+        prefill: unknown | null;
+    }>, getInput: GetInput<ExtractInputSpecType<InputSpecType>>, run: Run<ExtractInputSpecType<InputSpecType>>): Action<Id, ExtractInputSpecType<InputSpecType>>;
     static withoutInput<Id extends T.ActionId>(id: Id, metadata: MaybeFn<Omit<T.ActionMetadata, 'hasInput'>>, run: Run<{}>): Action<Id, {}>;
     exportMetadata(options: {
         effects: T.Effects;

package/base/lib/actions/setupActions.js

@@ -48,9 +48,12 @@ class Action {
     async getInput(options) {
         let spec = {};
         if (this.inputSpec) {
-            const built = await this.inputSpec.build(options);
-            this.prevInputSpec[options.effects.eventId] = built;
-            spec = built.spec;
+            const inputSpec = await callMaybeFn(this.inputSpec, options);
+            const built = await inputSpec?.build(options);
+            if (built) {
+                this.prevInputSpec[options.effects.eventId] = built;
+                spec = built.spec;
+            }
         }
         return {
             eventId: options.effects.eventId,

package/base/lib/actions/setupActions.js.map

@@ -1 +1 @@
-{"version":3,"file":"setupActions.js","sourceRoot":"","sources":["../../../../base/lib/actions/setupActions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setupActions.js","sourceRoot":"","sources":["../../../../base/lib/actions/setupActions.ts"],"names":[],"mappings":"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"}

package/base/lib/exver/index.d.ts

@@ -1,7 +1,38 @@
 import { DeepMap } from 'deep-equality-data-structures';
 import * as P from './exver';
+/**
+ * Compile-time utility type that validates a version string literal conforms to semver format.
+ *
+ * Resolves to `unknown` if valid, `never` if invalid. Used with {@link testTypeVersion}.
+ *
+ * @example
+ * ```ts
+ * type Valid = ValidateVersion<"1.2.3">     // unknown (valid)
+ * type Invalid = ValidateVersion<"-3">      // never (invalid)
+ * ```
+ */
 export type ValidateVersion<T extends String> = T extends `-${infer A}` ? never : T extends `${infer A}-${string}` ? ValidateVersion<A> : T extends `${bigint}` ? unknown : T extends `${bigint}.${infer A}` ? ValidateVersion<A> : never;
+/**
+ * Compile-time utility type that validates an extended version string literal.
+ *
+ * Extended versions have the format `upstream:downstream` or `#flavor:upstream:downstream`.
+ *
+ * @example
+ * ```ts
+ * type Valid = ValidateExVer<"1.2.3:0">           // valid
+ * type Flavored = ValidateExVer<"#bitcoin:1.0:0">  // valid
+ * type Bad = ValidateExVer<"1.2-3">                // never (invalid)
+ * ```
+ */
 export type ValidateExVer<T extends string> = T extends `#${string}:${infer A}:${infer B}` ? ValidateVersion<A> & ValidateVersion<B> : T extends `${infer A}:${infer B}` ? ValidateVersion<A> & ValidateVersion<B> : never;
+/**
+ * Validates a tuple of extended version string literals at compile time.
+ *
+ * @example
+ * ```ts
+ * type Valid = ValidateExVers<["1.0:0", "2.0:0"]>  // valid
+ * ```
+ */
 export type ValidateExVers<T> = T extends [] ? unknown[] : T extends [infer A, ...infer B] ? ValidateExVer<A & string> & ValidateExVers<B> : never[];
 type Anchor = {
     type: 'Anchor';
@@ -85,55 +116,234 @@ declare class VersionRangeTable {
      */
     static minterms(tables: VersionRangeTables): VersionRange;
 }
+/**
+ * Represents a parsed version range expression used to match against {@link Version} or {@link ExtendedVersion} values.
+ *
+ * Version ranges support standard comparison operators (`=`, `>`, `<`, `>=`, `<=`, `!=`),
+ * caret (`^`) and tilde (`~`) ranges, boolean logic (`&&`, `||`, `!`), and flavor matching (`#flavor`).
+ *
+ * @example
+ * ```ts
+ * const range = VersionRange.parse(">=1.0.0:0 && <2.0.0:0")
+ * const version = ExtendedVersion.parse("1.5.0:0")
+ * console.log(range.satisfiedBy(version)) // true
+ *
+ * // Combine ranges with boolean logic
+ * const combined = VersionRange.and(
+ *   VersionRange.parse(">=1.0:0"),
+ *   VersionRange.parse("<3.0:0"),
+ * )
+ *
+ * // Match a specific flavor
+ * const flavored = VersionRange.parse("#bitcoin")
+ * ```
+ */
 export declare class VersionRange {
     atom: Anchor | And | Or | Not | P.Any | P.None | Flavor;
     constructor(atom: Anchor | And | Or | Not | P.Any | P.None | Flavor);
     toStringParens(parent: 'And' | 'Or' | 'Not'): string;
+    /** Serializes this version range back to its canonical string representation. */
     toString(): string;
     private static parseAtom;
     private static parseRange;
+    /**
+     * Parses a version range string into a `VersionRange`.
+     *
+     * @param range - A version range expression, e.g. `">=1.0.0:0 && <2.0.0:0"`, `"^1.2:0"`, `"*"`
+     * @returns The parsed `VersionRange`
+     * @throws If the string is not a valid version range expression
+     */
     static parse(range: string): VersionRange;
+    /**
+     * Creates a version range from a comparison operator and an {@link ExtendedVersion}.
+     *
+     * @param operator - One of `"="`, `">"`, `"<"`, `">="`, `"<="`, `"!="`, `"^"`, `"~"`
+     * @param version - The version to compare against
+     */
     static anchor(operator: P.CmpOp, version: ExtendedVersion): VersionRange;
+    /**
+     * Creates a version range that matches only versions with the specified flavor.
+     *
+     * @param flavor - The flavor string to match, or `null` for the default (unflavored) variant
+     */
     static flavor(flavor: string | null): VersionRange;
+    /**
+     * Parses a legacy "emver" format version range string.
+     *
+     * @param range - A version range in the legacy emver format
+     * @returns The parsed `VersionRange`
+     */
     static parseEmver(range: string): VersionRange;
+    /** Returns the intersection of this range with another (logical AND). */
     and(right: VersionRange): VersionRange;
+    /** Returns the union of this range with another (logical OR). */
     or(right: VersionRange): VersionRange;
+    /** Returns the negation of this range (logical NOT). */
     not(): VersionRange;
+    /**
+     * Returns the logical AND (intersection) of multiple version ranges.
+     * Short-circuits on `none()` and skips `any()`.
+     */
     static and(...xs: Array<VersionRange>): VersionRange;
+    /**
+     * Returns the logical OR (union) of multiple version ranges.
+     * Short-circuits on `any()` and skips `none()`.
+     */
     static or(...xs: Array<VersionRange>): VersionRange;
+    /** Returns a version range that matches all versions (wildcard `*`). */
     static any(): VersionRange;
+    /** Returns a version range that matches no versions (`!`). */
     static none(): VersionRange;
+    /**
+     * Returns `true` if the given version satisfies this range.
+     *
+     * @param version - A {@link Version} or {@link ExtendedVersion} to test
+     */
     satisfiedBy(version: Version | ExtendedVersion): boolean;
     tables(): VersionRangeTables;
+    /** Returns `true` if any version exists that could satisfy this range. */
     satisfiable(): boolean;
+    /** Returns `true` if this range and `other` share at least one satisfying version. */
     intersects(other: VersionRange): boolean;
+    /**
+     * Returns a canonical (simplified) form of this range using minterm expansion.
+     * Useful for normalizing complex boolean expressions into a minimal representation.
+     */
     normalize(): VersionRange;
 }
+/**
+ * Represents a semantic version number with numeric segments and optional prerelease identifiers.
+ *
+ * Follows semver precedence rules: numeric segments are compared left-to-right,
+ * and a version with prerelease identifiers has lower precedence than the same version without.
+ *
+ * @example
+ * ```ts
+ * const v = Version.parse("1.2.3")
+ * console.log(v.toString())             // "1.2.3"
+ * console.log(v.compare(Version.parse("1.3.0"))) // "less"
+ *
+ * const pre = Version.parse("2.0.0-beta.1")
+ * console.log(pre.compare(Version.parse("2.0.0"))) // "less" (prerelease < release)
+ * ```
+ */
 export declare class Version {
+    /** The numeric version segments (e.g. `[1, 2, 3]` for `"1.2.3"`). */
     number: number[];
+    /** Optional prerelease identifiers (e.g. `["beta", 1]` for `"-beta.1"`). */
     prerelease: (string | number)[];
-    constructor(number: number[], prerelease: (string | number)[]);
+    constructor(
+    /** The numeric version segments (e.g. `[1, 2, 3]` for `"1.2.3"`). */
+    number: number[], 
+    /** Optional prerelease identifiers (e.g. `["beta", 1]` for `"-beta.1"`). */
+    prerelease: (string | number)[]);
+    /** Serializes this version to its string form (e.g. `"1.2.3"` or `"1.0.0-beta.1"`). */
     toString(): string;
+    /**
+     * Compares this version against another using semver precedence rules.
+     *
+     * @param other - The version to compare against
+     * @returns `'greater'`, `'equal'`, or `'less'`
+     */
     compare(other: Version): 'greater' | 'equal' | 'less';
+    /**
+     * Compares two versions, returning a numeric value suitable for use with `Array.sort()`.
+     *
+     * @returns `-1` if less, `0` if equal, `1` if greater
+     */
     compareForSort(other: Version): -1 | 0 | 1;
+    /**
+     * Parses a version string into a `Version` instance.
+     *
+     * @param version - A semver-compatible string, e.g. `"1.2.3"` or `"1.0.0-beta.1"`
+     * @throws If the string is not a valid version
+     */
     static parse(version: string): Version;
+    /**
+     * Returns `true` if this version satisfies the given {@link VersionRange}.
+     * Internally treats this as an unflavored {@link ExtendedVersion} with downstream `0`.
+     */
     satisfies(versionRange: VersionRange): boolean;
 }
+/**
+ * Represents an extended version with an optional flavor, an upstream version, and a downstream version.
+ *
+ * The format is `#flavor:upstream:downstream` (e.g. `#bitcoin:1.2.3:0`) or `upstream:downstream`
+ * for unflavored versions. Flavors allow multiple variants of a package to coexist.
+ *
+ * - **flavor**: An optional string identifier for the variant (e.g. `"bitcoin"`, `"litecoin"`)
+ * - **upstream**: The version of the upstream software being packaged
+ * - **downstream**: The version of the StartOS packaging itself
+ *
+ * Versions with different flavors are incomparable (comparison returns `null`).
+ *
+ * @example
+ * ```ts
+ * const v = ExtendedVersion.parse("#bitcoin:1.2.3:0")
+ * console.log(v.flavor)      // "bitcoin"
+ * console.log(v.upstream)    // Version { number: [1, 2, 3] }
+ * console.log(v.downstream)  // Version { number: [0] }
+ * console.log(v.toString())  // "#bitcoin:1.2.3:0"
+ *
+ * const range = VersionRange.parse(">=1.0.0:0")
+ * console.log(v.satisfies(range)) // true
+ * ```
+ */
 export declare class ExtendedVersion {
+    /** The flavor identifier (e.g. `"bitcoin"`), or `null` for unflavored versions. */
     flavor: string | null;
+    /** The upstream software version. */
     upstream: Version;
+    /** The downstream packaging version. */
     downstream: Version;
-    constructor(flavor: string | null, upstream: Version, downstream: Version);
+    constructor(
+    /** The flavor identifier (e.g. `"bitcoin"`), or `null` for unflavored versions. */
+    flavor: string | null, 
+    /** The upstream software version. */
+    upstream: Version, 
+    /** The downstream packaging version. */
+    downstream: Version);
+    /** Serializes this extended version to its string form (e.g. `"#bitcoin:1.2.3:0"` or `"1.0.0:1"`). */
     toString(): string;
+    /**
+     * Compares this extended version against another.
+     *
+     * @returns `'greater'`, `'equal'`, `'less'`, or `null` if the flavors differ (incomparable)
+     */
     compare(other: ExtendedVersion): 'greater' | 'equal' | 'less' | null;
+    /**
+     * Lexicographic comparison — compares flavors alphabetically first, then versions.
+     * Unlike {@link compare}, this never returns `null`: different flavors are ordered alphabetically.
+     */
     compareLexicographic(other: ExtendedVersion): 'greater' | 'equal' | 'less';
+    /**
+     * Returns a numeric comparison result suitable for use with `Array.sort()`.
+     * Uses lexicographic ordering (flavors sorted alphabetically, then by version).
+     */
     compareForSort(other: ExtendedVersion): 1 | 0 | -1;
+    /** Returns `true` if this version is strictly greater than `other`. Returns `false` if flavors differ. */
     greaterThan(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version is greater than or equal to `other`. Returns `false` if flavors differ. */
     greaterThanOrEqual(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version equals `other` (same flavor, upstream, and downstream). */
     equals(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version is strictly less than `other`. Returns `false` if flavors differ. */
     lessThan(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version is less than or equal to `other`. Returns `false` if flavors differ. */
     lessThanOrEqual(other: ExtendedVersion): boolean;
+    /**
+     * Parses an extended version string into an `ExtendedVersion`.
+     *
+     * @param extendedVersion - A string like `"1.2.3:0"` or `"#bitcoin:1.0.0:0"`
+     * @throws If the string is not a valid extended version
+     */
     static parse(extendedVersion: string): ExtendedVersion;
+    /**
+     * Parses a legacy "emver" format extended version string.
+     *
+     * @param extendedVersion - A version string in the legacy emver format
+     * @throws If the string is not a valid emver version (error message includes the input string)
+     */
     static parseEmver(extendedVersion: string): ExtendedVersion;
     /**
      * Returns an ExtendedVersion with the Upstream major version version incremented by 1
@@ -153,6 +363,27 @@ export declare class ExtendedVersion {
      */
     satisfies(versionRange: VersionRange): boolean;
 }
+/**
+ * Compile-time type-checking helper that validates an extended version string literal.
+ * If the string is invalid, TypeScript will report a type error at the call site.
+ *
+ * @example
+ * ```ts
+ * testTypeExVer("1.2.3:0")         // compiles
+ * testTypeExVer("#bitcoin:1.0:0")  // compiles
+ * testTypeExVer("invalid")         // type error
+ * ```
+ */
 export declare const testTypeExVer: <T extends string>(t: T & ValidateExVer<T>) => T & ValidateExVer<T>;
+/**
+ * Compile-time type-checking helper that validates a version string literal.
+ * If the string is invalid, TypeScript will report a type error at the call site.
+ *
+ * @example
+ * ```ts
+ * testTypeVersion("1.2.3")  // compiles
+ * testTypeVersion("-3")     // type error
+ * ```
+ */
 export declare const testTypeVersion: <T extends string>(t: T & ValidateVersion<T>) => T & ValidateVersion<T>;
 export {};