@timeax/digital-service-engine 0.0.1 → 0.0.2

package/dist/core/index.d.cts

@@ -30,59 +30,9 @@ 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;
@@ -143,6 +93,8 @@ type ServiceProps = {
     excludes_for_buttons?: Record<string, string[]>;
     schema_version?: string;
     fallbacks?: ServiceFallback;
+    name?: string;
+    notices?: ServicePropsNotice[];
 };
 type ServiceIdRef = number | string;
 type NodeIdRef = string;
@@ -152,6 +104,34 @@ type ServiceFallback = {
     /** Primary→fallback list used when no node-scoped entry is present */
     global?: Record<ServiceIdRef, ServiceIdRef[]>;
 };
+type NoticeType = "public" | "private";
+type NoticeSeverity = "info" | "warning" | "error";
+/**
+ * “label” is lightweight + UI-friendly (best, sale, hot, etc).
+ * Others remain semantic / governance oriented.
+ */
+type NoticeKind = "label" | "warning" | "deprecation" | "compat" | "migration" | "policy";
+type NoticeTarget = {
+    scope: "global";
+} | {
+    scope: "node";
+    node_kind: "tag" | "field" | "option";
+    node_id: string;
+};
+interface ServicePropsNotice {
+    id: string;
+    type: NoticeType;
+    kind: NoticeKind;
+    severity: NoticeSeverity;
+    target: NoticeTarget;
+    title: string;
+    description?: string;
+    reason?: string;
+    marked_at?: string;
+    icon?: string;
+    color?: string;
+    meta?: Record<string, unknown>;
+}
 
 type NodeKind$1 = "tag" | "field" | "comment" | "option";
 type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
@@ -213,6 +193,123 @@ type DgpServiceCapability = {
 };
 type DgpServiceMap = Record<string, DgpServiceCapability> & Record<number, DgpServiceCapability>;
 
+interface ButtonValue {
+    id: string;
+    value: string | number;
+    service_id?: number;
+    pricing_role?: "base" | "utility";
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+}
+type Scalar = string | number | boolean | ButtonValue | null;
+type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
+type QuantityRule = {
+    valueBy: "value" | "length" | "eval";
+    code?: string;
+};
+type UtilityLineItem = {
+    nodeId: string;
+    mode: UtilityMode;
+    rate: number;
+    inputs: {
+        quantity: number;
+        value?: Scalar | Scalar[];
+        valueBy?: "value" | "length" | "eval";
+        evalCodeUsed?: boolean;
+    };
+};
+type FallbackDiagnostics = {
+    scope: "node" | "global";
+    nodeId?: string;
+    primary: string | number;
+    candidate: string | number;
+    reasons: Array<"rate_violation" | "constraint_mismatch" | "unknown_service" | "ambiguous_context">;
+};
+type SnapshotContext = {
+    /** The single active tag id for this order */
+    tag: string;
+    /** Effective (post-propagation) constraints on that tag */
+    constraints: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+    /**
+     * Per-node evaluation context:
+     * - For the active tag node itself: the same tag id.
+     * - For an option node: parent's field.bind_id must include this tag to be applicable; otherwise null.
+     * - For a field node (optional to include later): same rule as option, derived from field.bind_id.
+     */
+    nodeContexts: Record<string, string | null>;
+    /** Client pruning policy used (so server can mirror/compare). */
+    policy: {
+        ratePolicy: {
+            kind: "lte_primary" | "none";
+            thresholdPct?: number;
+        };
+        requireConstraintFit: boolean;
+    };
+};
+type OrderSnapshot = {
+    version: "1";
+    mode: "prod" | "dev";
+    builtAt: string;
+    selection: {
+        tag: string;
+        fields: Array<{
+            id: string;
+            type: string;
+            selectedOptions?: string[];
+        }>;
+    };
+    inputs: {
+        form: Record<string, Scalar | Scalar[]>;
+        selections: Record<string, string[]>;
+    };
+    quantity: number;
+    quantitySource: {
+        kind: "field" | "tag" | "option" | "default";
+        id?: string;
+        rule?: QuantityRule;
+        defaultedFromHost?: boolean;
+    };
+    min: number;
+    max: number;
+    services: Array<string | number>;
+    serviceMap: Record<string, Array<string | number>>;
+    fallbacks?: {
+        nodes?: Record<string, Array<string | number>>;
+        global?: Record<string | number, Array<string | number>>;
+    };
+    utilities?: UtilityLineItem[];
+    warnings?: {
+        utility?: Array<{
+            nodeId: string;
+            reason: string;
+        }>;
+        fallbacks?: FallbackDiagnostics[];
+    };
+    meta?: {
+        schema_version?: string;
+        workspaceId?: string;
+        builder?: {
+            commit?: string;
+        };
+        context?: SnapshotContext;
+    };
+};
+
+type NodeRef = {
+    kind: "tag";
+    id: string;
+    node: Tag;
+} | {
+    kind: "field";
+    id: string;
+    node: Field;
+} | {
+    kind: "option";
+    id: string;
+    node: FieldOption;
+    fieldId: string;
+};
+type NodeMap = Map<string, NodeRef>;
+
 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;
@@ -261,6 +358,7 @@ type DynamicRule = {
 };
 type ValidatorOptions = {
     serviceMap?: DgpServiceMap;
+    nodeMap?: NodeMap;
     allowUnsafe?: boolean;
     selectedOptionKeys?: string[];
     globalUtilityGuard?: boolean;
@@ -294,7 +392,17 @@ type NormaliseOptions = {
 };
 declare function normalise(input: unknown, opts?: NormaliseOptions): ServiceProps;
 
+/**
+ * Core synchronous validate.
+ */
 declare function validate(props: ServiceProps, ctx?: ValidatorOptions): ValidationError[];
+/**
+ * UI-friendly async wrapper:
+ * - yields to microtask queue
+ * - then yields to the next animation frame (so paint can happen)
+ * - then runs validate()
+ */
+declare function validateAsync(props: ServiceProps, ctx?: ValidatorOptions): Promise<ValidationError[]>;
 
 /** Options you can set on the builder (used for validation/visibility) */
 type BuilderOptions = Omit<ValidatorOptions, "serviceMap"> & {
@@ -338,6 +446,10 @@ interface Builder {
         description: string;
         value: string;
     }[];
+    isTagId(id: string): boolean;
+    isFieldId(id: string): boolean;
+    isOptionId(id: string): boolean;
+    getNodeMap(): NodeMap;
 }
 declare function createBuilder(opts?: BuilderOptions): Builder;
 
@@ -504,4 +616,30 @@ interface NodeIndex {
 }
 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 };
+type BuildOrderSnapshotSettings = {
+    mode?: "prod" | "dev";
+    hostDefaultQuantity?: number;
+    /** Full fallback policy */
+    fallback?: FallbackSettings;
+    workspaceId?: string;
+    builderCommit?: string;
+};
+type BuildOrderSelection = {
+    /** Single active context (one tag) coming from Selection */
+    activeTagId: string;
+    /** Non-option inputs, keyed by fieldId (will be remapped to field.name in the payload) */
+    formValuesByFieldId: Record<string, Scalar | Scalar[]>;
+    /** Option selections, keyed by fieldId → optionId[] */
+    optionSelectionsByFieldId: Record<string, string[]>;
+    /**
+     * Selection visit order for options (optional, improves "first option wins primary" determinism).
+     * If omitted, iteration order falls back to Object.entries(optionSelectionsByFieldId).
+     */
+    optionTraversalOrder?: Array<{
+        fieldId: string;
+        optionId: string;
+    }>;
+};
+declare function buildOrderSnapshot(props: ServiceProps, builder: Builder, selection: BuildOrderSelection, services: DgpServiceMap, settings?: BuildOrderSnapshotSettings): OrderSnapshot;
+
+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, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createNodeIndex, getEligibleFallbacks, normalise, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };

package/dist/core/index.d.ts

@@ -30,59 +30,9 @@ 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;
@@ -143,6 +93,8 @@ type ServiceProps = {
     excludes_for_buttons?: Record<string, string[]>;
     schema_version?: string;
     fallbacks?: ServiceFallback;
+    name?: string;
+    notices?: ServicePropsNotice[];
 };
 type ServiceIdRef = number | string;
 type NodeIdRef = string;
@@ -152,6 +104,34 @@ type ServiceFallback = {
     /** Primary→fallback list used when no node-scoped entry is present */
     global?: Record<ServiceIdRef, ServiceIdRef[]>;
 };
+type NoticeType = "public" | "private";
+type NoticeSeverity = "info" | "warning" | "error";
+/**
+ * “label” is lightweight + UI-friendly (best, sale, hot, etc).
+ * Others remain semantic / governance oriented.
+ */
+type NoticeKind = "label" | "warning" | "deprecation" | "compat" | "migration" | "policy";
+type NoticeTarget = {
+    scope: "global";
+} | {
+    scope: "node";
+    node_kind: "tag" | "field" | "option";
+    node_id: string;
+};
+interface ServicePropsNotice {
+    id: string;
+    type: NoticeType;
+    kind: NoticeKind;
+    severity: NoticeSeverity;
+    target: NoticeTarget;
+    title: string;
+    description?: string;
+    reason?: string;
+    marked_at?: string;
+    icon?: string;
+    color?: string;
+    meta?: Record<string, unknown>;
+}
 
 type NodeKind$1 = "tag" | "field" | "comment" | "option";
 type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
@@ -213,6 +193,123 @@ type DgpServiceCapability = {
 };
 type DgpServiceMap = Record<string, DgpServiceCapability> & Record<number, DgpServiceCapability>;
 
+interface ButtonValue {
+    id: string;
+    value: string | number;
+    service_id?: number;
+    pricing_role?: "base" | "utility";
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+}
+type Scalar = string | number | boolean | ButtonValue | null;
+type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
+type QuantityRule = {
+    valueBy: "value" | "length" | "eval";
+    code?: string;
+};
+type UtilityLineItem = {
+    nodeId: string;
+    mode: UtilityMode;
+    rate: number;
+    inputs: {
+        quantity: number;
+        value?: Scalar | Scalar[];
+        valueBy?: "value" | "length" | "eval";
+        evalCodeUsed?: boolean;
+    };
+};
+type FallbackDiagnostics = {
+    scope: "node" | "global";
+    nodeId?: string;
+    primary: string | number;
+    candidate: string | number;
+    reasons: Array<"rate_violation" | "constraint_mismatch" | "unknown_service" | "ambiguous_context">;
+};
+type SnapshotContext = {
+    /** The single active tag id for this order */
+    tag: string;
+    /** Effective (post-propagation) constraints on that tag */
+    constraints: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+    /**
+     * Per-node evaluation context:
+     * - For the active tag node itself: the same tag id.
+     * - For an option node: parent's field.bind_id must include this tag to be applicable; otherwise null.
+     * - For a field node (optional to include later): same rule as option, derived from field.bind_id.
+     */
+    nodeContexts: Record<string, string | null>;
+    /** Client pruning policy used (so server can mirror/compare). */
+    policy: {
+        ratePolicy: {
+            kind: "lte_primary" | "none";
+            thresholdPct?: number;
+        };
+        requireConstraintFit: boolean;
+    };
+};
+type OrderSnapshot = {
+    version: "1";
+    mode: "prod" | "dev";
+    builtAt: string;
+    selection: {
+        tag: string;
+        fields: Array<{
+            id: string;
+            type: string;
+            selectedOptions?: string[];
+        }>;
+    };
+    inputs: {
+        form: Record<string, Scalar | Scalar[]>;
+        selections: Record<string, string[]>;
+    };
+    quantity: number;
+    quantitySource: {
+        kind: "field" | "tag" | "option" | "default";
+        id?: string;
+        rule?: QuantityRule;
+        defaultedFromHost?: boolean;
+    };
+    min: number;
+    max: number;
+    services: Array<string | number>;
+    serviceMap: Record<string, Array<string | number>>;
+    fallbacks?: {
+        nodes?: Record<string, Array<string | number>>;
+        global?: Record<string | number, Array<string | number>>;
+    };
+    utilities?: UtilityLineItem[];
+    warnings?: {
+        utility?: Array<{
+            nodeId: string;
+            reason: string;
+        }>;
+        fallbacks?: FallbackDiagnostics[];
+    };
+    meta?: {
+        schema_version?: string;
+        workspaceId?: string;
+        builder?: {
+            commit?: string;
+        };
+        context?: SnapshotContext;
+    };
+};
+
+type NodeRef = {
+    kind: "tag";
+    id: string;
+    node: Tag;
+} | {
+    kind: "field";
+    id: string;
+    node: Field;
+} | {
+    kind: "option";
+    id: string;
+    node: FieldOption;
+    fieldId: string;
+};
+type NodeMap = Map<string, NodeRef>;
+
 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;
@@ -261,6 +358,7 @@ type DynamicRule = {
 };
 type ValidatorOptions = {
     serviceMap?: DgpServiceMap;
+    nodeMap?: NodeMap;
     allowUnsafe?: boolean;
     selectedOptionKeys?: string[];
     globalUtilityGuard?: boolean;
@@ -294,7 +392,17 @@ type NormaliseOptions = {
 };
 declare function normalise(input: unknown, opts?: NormaliseOptions): ServiceProps;
 
+/**
+ * Core synchronous validate.
+ */
 declare function validate(props: ServiceProps, ctx?: ValidatorOptions): ValidationError[];
+/**
+ * UI-friendly async wrapper:
+ * - yields to microtask queue
+ * - then yields to the next animation frame (so paint can happen)
+ * - then runs validate()
+ */
+declare function validateAsync(props: ServiceProps, ctx?: ValidatorOptions): Promise<ValidationError[]>;
 
 /** Options you can set on the builder (used for validation/visibility) */
 type BuilderOptions = Omit<ValidatorOptions, "serviceMap"> & {
@@ -338,6 +446,10 @@ interface Builder {
         description: string;
         value: string;
     }[];
+    isTagId(id: string): boolean;
+    isFieldId(id: string): boolean;
+    isOptionId(id: string): boolean;
+    getNodeMap(): NodeMap;
 }
 declare function createBuilder(opts?: BuilderOptions): Builder;
 
@@ -504,4 +616,30 @@ interface NodeIndex {
 }
 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 };
+type BuildOrderSnapshotSettings = {
+    mode?: "prod" | "dev";
+    hostDefaultQuantity?: number;
+    /** Full fallback policy */
+    fallback?: FallbackSettings;
+    workspaceId?: string;
+    builderCommit?: string;
+};
+type BuildOrderSelection = {
+    /** Single active context (one tag) coming from Selection */
+    activeTagId: string;
+    /** Non-option inputs, keyed by fieldId (will be remapped to field.name in the payload) */
+    formValuesByFieldId: Record<string, Scalar | Scalar[]>;
+    /** Option selections, keyed by fieldId → optionId[] */
+    optionSelectionsByFieldId: Record<string, string[]>;
+    /**
+     * Selection visit order for options (optional, improves "first option wins primary" determinism).
+     * If omitted, iteration order falls back to Object.entries(optionSelectionsByFieldId).
+     */
+    optionTraversalOrder?: Array<{
+        fieldId: string;
+        optionId: string;
+    }>;
+};
+declare function buildOrderSnapshot(props: ServiceProps, builder: Builder, selection: BuildOrderSelection, services: DgpServiceMap, settings?: BuildOrderSnapshotSettings): OrderSnapshot;
+
+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, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createNodeIndex, getEligibleFallbacks, normalise, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };