@timeax/digital-service-engine 0.0.1

package/dist/schema/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/schema/index.ts
+var schema_exports = {};
+module.exports = __toCommonJS(schema_exports);
+//# sourceMappingURL=index.cjs.map

package/dist/schema/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/schema/index.ts"],"sourcesContent":["export * from \"./base\";\r\nexport * from \"./canvas-types\";\r\nexport * from \"./comments\";\r\nexport * from \"./editor\";\r\nexport * from \"./editor.types\";\r\nexport * from \"./graph\";\r\nexport * from \"./order\";\r\nexport * from \"./policies\";\r\nexport * from \"./provider\";\r\nexport * from \"./validation\";\r\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/schema/index.d.cts

@@ -0,0 +1,671 @@
+import { NodeProps } from 'reactflow';
+
+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[];
+}
+/** ---------------- Typed defaults helpers ---------------- */
+/**
+ * UiValue<U>: given a Ui node U, infer the runtime value type.
+ */
+type UiValue<U extends Ui> = U extends {
+    type: "string";
+} ? string : U extends {
+    type: "number";
+} ? number : U extends {
+    type: "boolean";
+} ? boolean : U extends {
+    type: "anyOf";
+    multiple: true;
+} ? Array<U["items"][number]["value"]> : U extends {
+    type: "anyOf";
+} ? U["items"][number]["value"] : U extends {
+    type: "array";
+    item: infer I extends Ui;
+} ? Array<UiValue<I>> : U extends {
+    type: "array";
+    items: infer T extends Ui[];
+} ? {
+    [K in keyof T]: UiValue<T[K]>;
+} : U extends {
+    type: "object";
+    fields: infer F extends Record<string, Ui>;
+} ? {
+    [K in keyof F]?: UiValue<F[K]>;
+} : unknown;
+/**
+ * FieldWithTypedDefaults<T>: same shape as BaseFieldUI, but:
+ *  - ui is a concrete map T (propName → Ui node)
+ *  - defaults are auto-typed from T via UiValue
+ */
+type FieldWithTypedDefaults<T extends Record<string, Ui>> = Omit<BaseFieldUI, "ui" | "defaults"> & {
+    ui: T;
+    defaults?: Partial<{
+        [K in keyof T]: UiValue<T[K]>;
+    }>;
+};
+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;
+/**
+ * Back-compat alias: older code may still import FlagKey.
+ * Keeping this prevents a wave of TS errors while still allowing any string key.
+ */
+type FlagKey = ConstraintKey;
+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 = "tag" | "field" | "comment" | "option";
+type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
+type GraphNode = {
+    id: string;
+    kind: NodeKind;
+    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 FlowNode = NodeProps<{
+    node: GraphNode;
+    [x: string]: any;
+}>;
+
+type CommentId = string;
+type ThreadId = string;
+type CommentAnchor = {
+    type: "node";
+    nodeId: string;
+    offset?: {
+        dx: number;
+        dy: number;
+    };
+} | {
+    type: "edge";
+    edgeId: string;
+    t?: number;
+} | {
+    type: "free";
+    position: {
+        x: number;
+        y: number;
+    };
+};
+type CommentMessage = {
+    id: CommentId;
+    isMain?: boolean;
+    authorId?: string;
+    authorName?: string;
+    body: string;
+    createdAt: number;
+    editedAt?: number;
+    meta?: Record<string, unknown>;
+};
+type CommentThread = {
+    id: ThreadId;
+    anchor?: CommentAnchor;
+    resolved: boolean;
+    createdAt: number;
+    updatedAt: number;
+    messages: CommentMessage[];
+    meta?: Record<string, unknown>;
+    _sync?: "pending" | "synced" | "error";
+};
+
+type Viewport = {
+    x: number;
+    y: number;
+    zoom: number;
+};
+type NodePos = {
+    x: number;
+    y: number;
+};
+type NodePositions = Record<string, NodePos>;
+type DraftWire = {
+    from: string;
+    kind: EdgeKind;
+};
+type CanvasState = {
+    graph: GraphSnapshot;
+    positions: NodePositions;
+    selection: Set<string>;
+    highlighted: Set<string>;
+    hoverId?: string;
+    viewport: Viewport;
+    draftWire?: DraftWire;
+    version: number;
+};
+type CanvasEvents = {
+    "graph:update": GraphSnapshot;
+    "state:change": CanvasState;
+    "selection:change": {
+        ids: string[];
+    };
+    "viewport:change": Viewport;
+    "hover:change": {
+        id?: string;
+    };
+    "wire:preview": {
+        from: string;
+        to?: string;
+        kind: EdgeKind;
+    };
+    "wire:commit": {
+        from: string;
+        to: string;
+        kind: EdgeKind;
+    };
+    "wire:cancel": {
+        from: string;
+    };
+    error: {
+        message: string;
+        code?: string;
+        meta?: any;
+    };
+    "comment:thread:create": {
+        thread: CommentThread;
+    };
+    "comment:thread:update": {
+        thread: CommentThread;
+    };
+    "comment:thread:delete": {
+        threadId: string;
+    };
+    "comment:message:create": {
+        threadId: string;
+        message: CommentMessage;
+    };
+    "comment:resolve": {
+        thread: CommentThread;
+        resolved: boolean;
+    };
+    "comment:move": {
+        thread: CommentThread;
+    };
+    "comment:select": {
+        threadId?: string;
+    };
+    "edge:change": EdgeKind;
+    "comment:sync": {
+        op: "create_thread" | "add_message" | "edit_message" | "delete_message" | "move_thread" | "resolve_thread" | "delete_thread";
+        threadId: string;
+        messageId?: string;
+        status: "scheduled" | "retrying" | "succeeded" | "failed" | "cancelled";
+        attempt: number;
+        nextDelayMs?: number;
+        error?: any;
+    };
+};
+type NodeView = GraphNode & {
+    position?: NodePos;
+};
+type EdgeView = GraphEdge;
+type CanvasOptions = {
+    initialViewport?: Partial<Viewport>;
+    autoEmitState?: boolean;
+};
+
+type CommentNode = {
+    id: string;
+    text: string;
+    status: "open" | "resolved";
+    anchor?: {
+        kind: "tag" | "field" | "option";
+        id: string;
+    };
+    replies?: Array<{
+        id: string;
+        text: string;
+        created_at: string;
+        author?: string;
+    }>;
+    xy?: {
+        x: number;
+        y: number;
+    };
+    meta?: Record<string, unknown>;
+};
+type EdgeRoute = {
+    id: string;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+};
+type LayoutState = {
+    canvas: CanvasState;
+    edges?: EdgeRoute[];
+};
+type EditorSnapshot = {
+    props: ServiceProps;
+    layout?: LayoutState;
+    comments?: CommentNode[];
+    meta?: Record<string, unknown>;
+};
+
+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 Env = "client" | "workspace";
+type SelectionOptions = {
+    env?: Env;
+    rootTagId?: string;
+    /** Resolve service capability from an id (used for `services` array) */
+    resolveService?: (id: any) => DgpServiceCapability | undefined;
+};
+
+type EditorEvents = {
+    "editor:command": {
+        name: string;
+        payload?: any;
+    };
+    "editor:change": {
+        props: ServiceProps;
+        reason: string;
+        command?: string;
+    };
+    "editor:undo": {
+        stackSize: number;
+        index: number;
+    };
+    "editor:redo": {
+        stackSize: number;
+        index: number;
+    };
+    "editor:error": {
+        message: string;
+        code?: string;
+        meta?: any;
+    };
+};
+type Command = {
+    name: string;
+    do(): void;
+    undo(): void;
+};
+type EditorOptions = {
+    historyLimit?: number;
+    validateAfterEach?: boolean;
+    /** Sync existence check; return true if the service exists. */
+    serviceExists?: (id: number) => boolean;
+    /** Optional local index; used if serviceExists is not provided. */
+    serviceMap?: Record<number, unknown>;
+    /** Raw policies JSON; will be compiled on demand by filterServicesForVisibleGroup. */
+    policiesRaw?: unknown;
+    selectionProps?: SelectionOptions;
+};
+type ConnectKind = "bind" | "include" | "exclude";
+
+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 ServiceFallbacks = {
+    nodes?: Record<string, Array<string | number>>;
+    global?: Record<string | number, Array<string | number>>;
+};
+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;
+    };
+    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;
+    };
+};
+
+/** Exported alias so the schema generator can target an array */
+type AdminPolicies = DynamicRule[];
+
+export type { AdminPolicies, BaseFieldUI, ButtonValue, CanvasEvents, CanvasOptions, CanvasState, Command, CommentAnchor, CommentId, CommentMessage, CommentNode, CommentThread, ConnectKind, ConstraintKey, DgpServiceCapability, DgpServiceMap, DraftWire, DynamicRule, EdgeKind, EdgeRoute, EdgeView, EditorEvents, EditorOptions, EditorSnapshot, FallbackDiagnostics, FallbackSettings, Field, FieldOption, FieldType, FieldWithTypedDefaults, FlagKey, FlowNode, GraphEdge, GraphNode, GraphSnapshot, IdType, LayoutState, NodeIdRef, NodeKind, NodePos, NodePositions, NodeView, OrderSnapshot, PricingRole, QuantityMark, QuantityRule, RatePolicy, Scalar, ServiceEstimates, ServiceFallback, ServiceFallbacks, ServiceFlag, ServiceFlags, ServiceIdRef, ServiceProps, ServiceWhereClause, ServiceWhereOp, SnapshotContext, SpeedEstimate, Tag, ThreadId, TimeRangeEstimate, Ui, UiAnyOf, UiArray, UiBoolean, UiNumber, UiObject, UiString, UiValue, UtilityLineItem, UtilityMark, UtilityMode, ValidationCode, ValidationError, ValidatorOptions, Viewport, WithQuantityDefault };