@timeax/digital-service-engine 0.0.1

package/dist/core/index.d.ts

@@ -0,0 +1,507 @@
+type PricingRole = "base" | "utility";
+type FieldType = "custom" | (string & {});
+/** ── Marker types (live inside meta; non-breaking) ───────────────────── */
+type QuantityMark = {
+    quantity?: {
+        valueBy: "value" | "length" | "eval";
+        code?: string;
+        multiply?: number;
+        clamp?: {
+            min?: number;
+            max?: number;
+        };
+        fallback?: number;
+    };
+};
+type UtilityMark = {
+    utility?: {
+        rate: number;
+        mode: "flat" | "per_quantity" | "per_value" | "percent";
+        valueBy?: "value" | "length";
+        percentBase?: "service_total" | "base_service" | "all";
+        label?: string;
+    };
+};
+type WithQuantityDefault = {
+    quantityDefault?: number;
+};
+/** ---------------- Core schema (as you designed) ---------------- */
+interface BaseFieldUI {
+    name?: string;
+    label: string;
+    required?: boolean;
+    /** Host-defined prop names → typed UI nodes */
+    ui?: Record<string, Ui>;
+    /** Host-defined prop names → runtime default values (untyped base) */
+    defaults?: Record<string, unknown>;
+}
+type Ui = UiString | UiNumber | UiBoolean | UiAnyOf | UiArray | UiObject;
+/** string */
+interface UiString {
+    type: "string";
+    enum?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+/** number */
+interface UiNumber {
+    type: "number";
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+}
+/** boolean */
+interface UiBoolean {
+    type: "boolean";
+}
+/** enumerated choices */
+interface UiAnyOf {
+    type: "anyOf";
+    multiple?: boolean;
+    items: Array<{
+        type: "string" | "number" | "boolean";
+        title?: string;
+        description?: string;
+        value: string | number | boolean;
+    }>;
+}
+/** arrays: homogeneous (item) or tuple (items) */
+interface UiArray {
+    type: "array";
+    item?: Ui;
+    items?: Ui[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+}
+/** objects: nested props */
+interface UiObject {
+    type: "object";
+    fields: Record<string, Ui>;
+    required?: string[];
+    order?: string[];
+}
+type FieldOption = {
+    id: string;
+    label: string;
+    value?: string | number;
+    service_id?: number;
+    pricing_role?: PricingRole;
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+};
+type Field = BaseFieldUI & {
+    id: string;
+    type: FieldType;
+    bind_id?: string | string[];
+    name?: string;
+    options?: FieldOption[];
+    description?: string;
+    component?: string;
+    pricing_role?: PricingRole;
+    meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
+        multi?: boolean;
+    };
+} & ({
+    button?: false;
+    service_id?: undefined;
+} | ({
+    button: true;
+    service_id?: number;
+} & WithQuantityDefault));
+type ConstraintKey = string;
+type Tag = {
+    id: string;
+    label: string;
+    bind_id?: string;
+    service_id?: number;
+    includes?: string[];
+    excludes?: string[];
+    meta?: Record<string, unknown> & WithQuantityDefault;
+    /**
+     * Which flags are set for this tag. If a flag is not set, it's inherited from the nearest ancestor with a value set.
+     */
+    constraints?: Partial<Record<ConstraintKey, boolean>>;
+    /** Which ancestor defined the *effective* value for each flag (nearest source). */
+    constraints_origin?: Partial<Record<ConstraintKey, string>>;
+    /**
+     * Present only when a child explicitly set a different value but was overridden
+     * by an ancestor during normalisation.
+     */
+    constraints_overrides?: Partial<Record<ConstraintKey, {
+        from: boolean;
+        to: boolean;
+        origin: string;
+    }>>;
+};
+type ServiceProps = {
+    order_for_tags?: Record<string, string[]>;
+    filters: Tag[];
+    fields: Field[];
+    includes_for_buttons?: Record<string, string[]>;
+    excludes_for_buttons?: Record<string, string[]>;
+    schema_version?: string;
+    fallbacks?: ServiceFallback;
+};
+type ServiceIdRef = number | string;
+type NodeIdRef = string;
+type ServiceFallback = {
+    /** Node-scoped fallbacks: prefer these when that node’s primary service fails */
+    nodes?: Record<NodeIdRef, ServiceIdRef[]>;
+    /** Primary→fallback list used when no node-scoped entry is present */
+    global?: Record<ServiceIdRef, ServiceIdRef[]>;
+};
+
+type NodeKind$1 = "tag" | "field" | "comment" | "option";
+type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
+type GraphNode = {
+    id: string;
+    kind: NodeKind$1;
+    bind_type?: "bound" | "utility" | null;
+    errors?: string[];
+    label: string;
+};
+type GraphEdge = {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    meta?: Record<string, unknown>;
+};
+type GraphSnapshot = {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+
+type TimeRangeEstimate = {
+    min_seconds?: number;
+    max_seconds?: number;
+    label?: string;
+    meta?: Record<string, unknown>;
+};
+type SpeedEstimate = {
+    amount?: number;
+    per?: "minute" | "hour" | "day" | "week" | "month";
+    unit?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+};
+type ServiceEstimates = {
+    start?: TimeRangeEstimate;
+    speed?: SpeedEstimate;
+    average?: TimeRangeEstimate;
+    meta?: Record<string, unknown>;
+};
+type ServiceFlag = {
+    enabled: boolean;
+    description: string;
+    meta?: Record<string, unknown>;
+};
+type IdType = string | number;
+type ServiceFlags = Record<string, ServiceFlag>;
+type DgpServiceCapability = {
+    id: IdType;
+    name?: string;
+    rate: number;
+    min?: number;
+    max?: number;
+    category?: string;
+    flags?: ServiceFlags;
+    estimates?: ServiceEstimates;
+    meta?: Record<string, unknown>;
+    [x: string]: any;
+};
+type DgpServiceMap = Record<string, DgpServiceCapability> & Record<number, DgpServiceCapability>;
+
+type ValidationCode = "root_missing" | "cycle_in_tags" | "bad_bind_reference" | "duplicate_id" | "duplicate_tag_label" | "duplicate_field_name" | "label_missing" | "duplicate_visible_label" | "bad_option_key" | "option_include_exclude_conflict" | "service_field_missing_service_id" | "user_input_field_has_service_option" | "rate_mismatch_across_base" | "utility_without_base" | "unsupported_constraint" | "constraint_contradiction" | "custom_component_missing" | "policy_violation" | "field_unbound" | "constraint_overridden" | "unsupported_constraint_option" | "custom_component_unresolvable" | "quantity_multiple_markers" | "utility_with_service_id" | "utility_missing_rate" | "utility_invalid_mode" | "fallback_bad_node" | "fallback_unknown_service" | "fallback_cycle" | "fallback_no_primary" | "fallback_rate_violation" | "fallback_constraint_mismatch" | "fallback_no_tag_context";
+type ValidationError = {
+    code: ValidationCode;
+    message: string;
+    severity: "error" | "warning" | "info";
+    nodeId?: string;
+    details?: Record<string, unknown> & {
+        affectedIds?: string[];
+    };
+};
+type ServiceWhereOp = "eq" | "neq" | "in" | "nin" | "exists" | "truthy" | "falsy" | "sw";
+/**
+ * Host-extensible service filter clause.
+ * `path` should usually be "service.<prop>" or "service.meta.<prop>" etc.
+ */
+type ServiceWhereClause = {
+    path: string;
+    op?: ServiceWhereOp;
+    value?: unknown;
+};
+type DynamicRule = {
+    id: string;
+    label?: string;
+    scope: "global" | "visible_group";
+    subject: "services";
+    /**
+     * Package-level filter surface:
+     * - role/tag/field are core to the builder schema
+     * - where[] allows hosts to filter against extra service properties (handler_id/platform_id/type/key/category_id/etc.)
+     */
+    filter?: {
+        role?: "base" | "utility" | "both";
+        tag_id?: string | string[];
+        field_id?: string | string[];
+        where?: ServiceWhereClause[];
+    };
+    /**
+     * Projection is intentionally open:
+     * hosts may project custom service properties.
+     */
+    projection?: "service.id" | "service.name" | "service.rate" | "service.min" | "service.max" | "service.category" | string;
+    op: "all_equal" | "unique" | "no_mix" | "all_true" | "any_true" | "max_count" | "min_count";
+    value?: number | boolean;
+    severity?: "error" | "warning";
+    message?: string;
+};
+type ValidatorOptions = {
+    serviceMap?: DgpServiceMap;
+    allowUnsafe?: boolean;
+    selectedOptionKeys?: string[];
+    globalUtilityGuard?: boolean;
+    policies?: DynamicRule[];
+    fallbackSettings?: FallbackSettings;
+};
+type RatePolicy = {
+    kind: "lte_primary";
+} | {
+    kind: "within_pct";
+    pct: number;
+} | {
+    kind: "at_least_pct_lower";
+    pct: number;
+};
+type FallbackSettings = {
+    /** Require fallbacks to satisfy tag constraints (dripfeed/refill/cancel) when a tag context is known. Default: true */
+    requireConstraintFit?: boolean;
+    /** Rate rule policy. Default: { kind: 'lte_primary' } i.e. candidate.rate <= primary.rate */
+    ratePolicy?: RatePolicy;
+    /** When multiple candidates remain, choose first (priority) or cheapest. Default: 'priority' */
+    selectionStrategy?: "priority" | "cheapest";
+    /** Validation mode: 'strict' → node-scoped violations reported as ValidationError; 'dev' → only collect diagnostics. Default: 'strict' */
+    mode?: "strict" | "dev";
+};
+
+type NormaliseOptions = {
+    /** default pricing role for fields/options when missing */
+    defaultPricingRole?: PricingRole;
+    constraints?: string[];
+};
+declare function normalise(input: unknown, opts?: NormaliseOptions): ServiceProps;
+
+declare function validate(props: ServiceProps, ctx?: ValidatorOptions): ValidationError[];
+
+/** Options you can set on the builder (used for validation/visibility) */
+type BuilderOptions = Omit<ValidatorOptions, "serviceMap"> & {
+    serviceMap?: DgpServiceMap;
+    /** max history entries for undo/redo */
+    historyLimit?: number;
+    /**
+     * Field ids whose options should be shown as nodes in the graph.
+     * If a field id is NOT in this set, its options are not materialized as nodes:
+     * - include/exclude wires keyed by an option id will be drawn from the FIELD instead.
+     */
+    showOptionNodes?: Set<string> | string[];
+};
+interface Builder {
+    /** Replace current payload (injects root if missing, rebuilds indexes) */
+    load(props: ServiceProps): void;
+    /** Graph for visualisation */
+    tree(): GraphSnapshot;
+    /** Deterministic save payload (drops unbound utility fields, prunes dead maps) */
+    cleanedProps(): ServiceProps;
+    /** Validation errors for current state */
+    errors(): ValidationError[];
+    /**
+     * Compute IDs of fields visible under a tag.
+     * If selectedOptionKeys provided, applies option-level include/exclude.
+     * NOTE: keys are “button ids”: either option.id or field.id for option-less buttons.
+     */
+    visibleFields(tagId: string, selectedOptionKeys?: string[]): string[];
+    /** Update builder options (validator context etc.) */
+    setOptions(patch: Partial<BuilderOptions>): void;
+    /** History */
+    undo(): boolean;
+    redo(): boolean;
+    /** Access the current props (already normalised) */
+    getProps(): ServiceProps;
+    /** Service map for validation/rules */
+    getServiceMap(): DgpServiceMap;
+    getConstraints(): {
+        id: string;
+        label: string;
+        description: string;
+        value: string;
+    }[];
+}
+declare function createBuilder(opts?: BuilderOptions): Builder;
+
+type FailedFallbackContext = {
+    scope: "node" | "global";
+    nodeId?: string;
+    primary: ServiceIdRef;
+    candidate: ServiceIdRef;
+    tagContext?: string;
+    reason: "unknown_service" | "no_primary" | "rate_violation" | "constraint_mismatch" | "cycle" | "no_tag_context";
+    details?: Record<string, unknown>;
+};
+declare function resolveServiceFallback(params: {
+    primary: ServiceIdRef;
+    nodeId?: NodeIdRef;
+    tagId?: string;
+    services: DgpServiceMap;
+    fallbacks?: ServiceFallback;
+    settings?: FallbackSettings;
+    props: ServiceProps;
+}): ServiceIdRef | null;
+declare function collectFailedFallbacks(props: ServiceProps, services: DgpServiceMap, settings?: FallbackSettings): FailedFallbackContext[];
+/**
+ * Return all fallback candidates that are eligible for the given primary,
+ * respecting:
+ *  - node-scoped list first (if nodeId provided), then global list for `primary`
+ *  - rate policy vs. primary
+ *  - (optional) tag constraint fit, only when tagId is provided and requireConstraintFit=true
+ *  - excludes (including primary automatically)
+ *  - selectionStrategy: 'priority' keeps list order, 'cheapest' sorts by rate asc
+ *  - unique (dedupe) and optional limit
+ */
+declare function getEligibleFallbacks(params: {
+    primary: ServiceIdRef;
+    nodeId?: NodeIdRef;
+    tagId?: string;
+    services: DgpServiceMap;
+    fallbacks?: ServiceFallback;
+    settings?: FallbackSettings;
+    props: ServiceProps;
+    exclude?: Array<ServiceIdRef>;
+    unique?: boolean;
+    limit?: number;
+}): ServiceIdRef[];
+
+type BaseCandidate = {
+    kind: "field" | "option";
+    id: string;
+    label?: string;
+    service_id: number;
+    rate: number;
+};
+/** Result for each violation discovered during deep simulation. */
+type RateCoherenceDiagnostic = {
+    scope: "visible_group";
+    tagId: string;
+    /** The “primary” used for comparison in this simulation:
+     *  anchor service if present; otherwise, the first base service among simulated candidates.
+     *  (Tag service is never used as primary.)
+     */
+    primary: BaseCandidate;
+    /** The item that violated the policy against the primary. */
+    offender: {
+        kind: "field" | "option";
+        id: string;
+        label?: string;
+        service_id: number;
+        rate: number;
+    };
+    policy: RatePolicy["kind"];
+    policyPct?: number;
+    message: string;
+    /** Which button triggered this simulation */
+    simulationAnchor: {
+        kind: "field" | "option";
+        id: string;
+        fieldId: string;
+        label?: string;
+    };
+};
+/** Run deep rate-coherence validation by simulating each button selection in the active tag. */
+declare function validateRateCoherenceDeep(params: {
+    builder: Builder;
+    services: DgpServiceMap;
+    tagId: string;
+    /** Optional rate policy (defaults to { kind: 'lte_primary' }) */
+    ratePolicy?: RatePolicy;
+}): RateCoherenceDiagnostic[];
+
+type NodeKind = "tag" | "field" | "option" | "unknown";
+type RelKind = "self" | "ancestor" | "descendant" | "unrelated";
+interface AncestryHit {
+    kind: RelKind;
+    node: TagNode;
+    index: number;
+    direct: boolean;
+    path: string[];
+}
+interface WithAncestry {
+    ancestry(baseTag: string | TagNode): readonly AncestryHit[];
+    isAncestorOf(baseTag: string | TagNode): boolean;
+    isDescendantOf(baseTag: string | TagNode): boolean;
+    isWithin(baseTag: string | TagNode): boolean;
+}
+interface TagNode extends WithAncestry {
+    kind: "tag";
+    id: string;
+    raw: Tag;
+    includes: ReadonlySet<string>;
+    excludes: ReadonlySet<string>;
+    isInherited?: boolean;
+    parent(): TagNode | undefined;
+    children(): readonly TagNode[];
+    ancestors(): readonly {
+        node: TagNode;
+        direct: boolean;
+        index: number;
+        path: string[];
+    }[];
+    pathTo(descendant: string | TagNode): string[] | null;
+    isBoundTo(tagId: string | TagNode): boolean;
+    getDescendant(id: string): FieldNode | undefined;
+    getDescendants(): readonly FieldNode[];
+}
+interface FieldNode extends WithAncestry {
+    kind: "field";
+    id: string;
+    raw: Field;
+    includes: ReadonlySet<string>;
+    excludes: ReadonlySet<string>;
+    isInherited?: boolean;
+    bindIds(): readonly string[];
+    ownerTags(): readonly TagNode[];
+    isBoundTo(tagId: string | TagNode): boolean;
+    getDescendant(id: string, contextId?: string): FieldNode | undefined;
+    getDescendants(tagId?: string): readonly FieldNode[];
+}
+interface OptionNode extends WithAncestry {
+    kind: "option";
+    id: string;
+    raw: FieldOption;
+    includes: ReadonlySet<string>;
+    excludes: ReadonlySet<string>;
+    isInherited?: boolean;
+    field(): FieldNode;
+    ownerTags(): readonly TagNode[];
+    isBoundTo(tagId: string | TagNode): boolean;
+    getDescendant(id: string, contextId?: string): FieldNode | undefined;
+    getDescendants(tagId?: string): readonly FieldNode[];
+}
+interface UnknownNode extends WithAncestry {
+    kind: "unknown";
+    id: string;
+    includes: ReadonlySet<string>;
+    excludes: ReadonlySet<string>;
+    isInherited?: boolean;
+}
+type AnyNode = TagNode | FieldNode | OptionNode | UnknownNode;
+interface NodeIndex {
+    getNode(input: string | Tag | Field | FieldOption): AnyNode;
+    getTag(id: string): TagNode | undefined;
+    getField(id: string): FieldNode | undefined;
+    getOption(id: string): OptionNode | undefined;
+}
+declare function createNodeIndex(builder: Builder): NodeIndex;
+
+export { type AncestryHit, type AnyNode, type Builder, type BuilderOptions, type FailedFallbackContext, type FieldNode, type NodeIndex, type NodeKind, type NormaliseOptions, type OptionNode, type RateCoherenceDiagnostic, type RelKind, type TagNode, type UnknownNode, type WithAncestry, collectFailedFallbacks, createBuilder, createNodeIndex, getEligibleFallbacks, normalise, resolveServiceFallback, validate, validateRateCoherenceDeep };