@getrheo/flow-runtime 1.0.0

package/dist/stateMachine.js

@@ -0,0 +1,674 @@
+import { permissionCaptureFieldKey, appReviewCaptureFieldKey, oauthLoginResponseKey, emailPasswordAuthResponseKey, OS_PERMISSION_OUTCOME_END, OS_PERMISSION_OUTCOME_CONTINUE, isInputLayer } from '@getrheo/contracts/layers';
+import '@getrheo/contracts/localized';
+import { EXTERNAL_SURFACE_NO_NEXT } from '@getrheo/contracts/decisions';
+
+// src/stateMachine/stepResponse.ts
+var externalSurfaceResponseKey = (nodeId) => `surface_${nodeId}`;
+var isEligibleConsumedDraft = (r) => {
+  switch (r.kind) {
+    case "text":
+    case "choice":
+    case "multiChoice":
+    case "scale":
+    case "cta":
+    case "carousel":
+      return true;
+    default:
+      return false;
+  }
+};
+
+// src/stateMachine/flowSession.ts
+var findScreen = (manifest, screenId) => manifest.screens.find((s) => s.id === screenId);
+var findExternalSurface = (manifest, nodeId) => (
+  // Older / hand-constructed manifests may omit `externalSurfaceNodes` entirely;
+  // treat that as "no surfaces" rather than crashing the state machine.
+  (manifest.externalSurfaceNodes ?? []).find((n) => n.id === nodeId)
+);
+var initFlowState = (manifest, sessionPartial) => ({
+  manifest,
+  currentScreenId: null,
+  pendingExternalSurface: null,
+  history: [],
+  responses: {},
+  session: {
+    locale: sessionPartial?.locale ?? manifest.defaultLocale,
+    platform: sessionPartial?.platform ?? "unknown",
+    sdkAttributes: sessionPartial?.sdkAttributes ?? {}
+  },
+  status: "idle",
+  startedAt: null,
+  completedAt: null
+});
+var walkLayers = (root, fn) => {
+  const visit = (l, depth) => {
+    fn(l, depth);
+    if (l.kind === "stack") l.children.forEach((c) => visit(c, depth + 1));
+    else if (l.kind === "carousel") l.slides.forEach((c) => visit(c, depth + 1));
+    else if (l.kind === "button") l.children.forEach((c) => visit(c, depth + 1));
+    else if (l.kind === "back_button") l.children.forEach((c) => visit(c, depth + 1));
+    else if (l.kind === "hyperlink") l.children.forEach((c) => visit(c, depth + 1));
+    else if (l.kind === "single_choice" || l.kind === "multiple_choice") {
+      l.children.forEach((c) => visit(c, depth + 1));
+    } else if (l.kind === "text_input" || l.kind === "scale_input") {
+      l.children?.forEach((c) => visit(c, depth + 1));
+    } else if (l.kind === "oauth_login") {
+      l.children.forEach((c) => visit(c, depth + 1));
+    } else if (l.kind === "oauth_provider" && l.variant === "custom") {
+      l.children.forEach((c) => visit(c, depth + 1));
+    } else if (l.kind === "email_password_auth") {
+      l.children.forEach((c) => visit(c, depth + 1));
+    } else if (l.kind === "email_password_field") {
+      l.children?.forEach((c) => visit(c, depth + 1));
+    } else if (l.kind === "email_password_submit") {
+      l.children.forEach((c) => visit(c, depth + 1));
+    }
+  };
+  visit(root, 0);
+};
+var walkScreen = (screen, fn) => {
+  if (screen.regions.header) walkLayers(screen.regions.header, fn);
+  walkLayers(screen.regions.body, fn);
+  if (screen.regions.footer) walkLayers(screen.regions.footer, fn);
+};
+var findInputLayer = (screen) => {
+  let found = null;
+  walkScreen(screen, (l) => {
+    if (!found && isInputLayer(l)) found = l;
+  });
+  return found;
+};
+var findManualSubmitInputLayer = (screen) => {
+  const input = findInputLayer(screen);
+  if (!input) return null;
+  if (input.kind === "multiple_choice" || input.kind === "text_input" || input.kind === "scale_input") {
+    return input;
+  }
+  return null;
+};
+var findLayerById = (screen, id) => {
+  let found = null;
+  walkScreen(screen, (l) => {
+    if (!found && l.id === id) found = l;
+  });
+  return found;
+};
+
+// src/decisionEval.ts
+var findDecisionNode = (manifest, id) => (manifest.decisionNodes ?? []).find((d) => d.id === id);
+var stableSerialize = (value) => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableSerialize).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${stableSerialize(value[k])}`);
+  return `{${parts.join(",")}}`;
+};
+var digestDecisionExpression = (expr) => {
+  const s = stableSerialize(expr);
+  let h = 5381;
+  for (let i = 0; i < s.length; i += 1) {
+    h = h * 33 ^ s.charCodeAt(i);
+  }
+  return `d${(h >>> 0).toString(16)}`;
+};
+var responseForField = (fieldKey, responses) => responses[fieldKey];
+var normalizeResponseValue = (r) => {
+  if (!r || typeof r !== "object") return void 0;
+  const o = r;
+  switch (o.kind) {
+    case "choice":
+      return typeof o.choiceId === "string" ? o.choiceId : void 0;
+    case "multiChoice":
+      return Array.isArray(o.choiceIds) ? o.choiceIds : void 0;
+    case "text":
+      return typeof o.value === "string" ? o.value : void 0;
+    case "scale":
+      return typeof o.value === "number" ? o.value : void 0;
+    case "checkbox":
+      return typeof o.value === "boolean" ? o.value : void 0;
+    default:
+      return void 0;
+  }
+};
+var normalizeScalarForStringPred = (raw) => {
+  if (raw === void 0 || raw === null) return void 0;
+  if (typeof raw === "string") return raw;
+  if (typeof raw === "number" && Number.isFinite(raw)) return String(raw);
+  return void 0;
+};
+var normalizeNumber = (raw) => {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return void 0;
+  return raw;
+};
+var normalizeChoiceId = (raw) => typeof raw === "string" && raw.length > 0 ? raw : void 0;
+var normalizeChoiceIds = (raw) => {
+  if (!Array.isArray(raw)) return void 0;
+  const ids = raw.filter((x) => typeof x === "string" && x.length > 0);
+  return ids;
+};
+var normalizeBoolean = (raw) => {
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw !== 0;
+  if (typeof raw === "string") {
+    const s = raw.trim().toLowerCase();
+    if (s === "true" || s === "1" || s === "yes") return true;
+    if (s === "false" || s === "0" || s === "no") return false;
+  }
+  return void 0;
+};
+var resolveVariableValue = (variable, ctx) => {
+  if (variable.kind === "builtin") {
+    if (variable.name === "locale") return ctx.locale;
+    return ctx.platform;
+  }
+  if (variable.kind === "sdk") return ctx.sdkAttributes[variable.key];
+  const r = responseForField(variable.fieldKey, ctx.responses);
+  return normalizeResponseValue(r);
+};
+var evalStringPred = (left, pred) => {
+  switch (pred.op) {
+    case "eq":
+      return left === pred.value;
+    case "neq":
+      return left !== pred.value;
+    case "contains":
+      return left.includes(pred.value);
+    default:
+      return false;
+  }
+};
+var evalNumberPred = (left, pred) => {
+  switch (pred.op) {
+    case "eq":
+      return left === pred.value;
+    case "neq":
+      return left !== pred.value;
+    case "lt":
+      return left < pred.value;
+    case "lte":
+      return left <= pred.value;
+    case "gt":
+      return left > pred.value;
+    case "gte":
+      return left >= pred.value;
+    default:
+      return false;
+  }
+};
+var evalChoicePred = (choiceId, pred) => {
+  if (pred.op === "eq") return choiceId === pred.optionId;
+  return pred.optionIds.includes(choiceId);
+};
+var setIntersect = (a, b) => {
+  const bs = new Set(b);
+  return a.filter((x) => bs.has(x));
+};
+var evalBooleanPred = (left, pred) => {
+  if (pred.op === "eq") return left === pred.value;
+  return left !== pred.value;
+};
+var evalMultiPred = (selected, pred) => {
+  const required = pred.optionIds;
+  switch (pred.op) {
+    case "intersects":
+      return setIntersect(selected, required).length > 0;
+    case "contains_all": {
+      const sel = new Set(selected);
+      return required.every((id) => sel.has(id));
+    }
+    case "subset_of": {
+      const allow = new Set(required);
+      return selected.every((id) => allow.has(id));
+    }
+    default:
+      return false;
+  }
+};
+var evaluateDecisionExpression = (expr, ctx) => {
+  if (expr.kind === "empty") return false;
+  if (expr.kind === "group") {
+    if (expr.op === "and") {
+      for (const c of expr.children) {
+        if (!evaluateDecisionExpression(c, ctx)) return false;
+      }
+      return true;
+    }
+    for (const c of expr.children) {
+      if (evaluateDecisionExpression(c, ctx)) return true;
+    }
+    return false;
+  }
+  const raw = resolveVariableValue(expr.variable, ctx);
+  const { predicate } = expr;
+  switch (predicate.type) {
+    case "string": {
+      const s = normalizeScalarForStringPred(raw);
+      if (s === void 0) return false;
+      return evalStringPred(s, predicate.pred);
+    }
+    case "number": {
+      const n = normalizeNumber(raw);
+      if (n === void 0) return false;
+      return evalNumberPred(n, predicate.pred);
+    }
+    case "choice": {
+      const id = normalizeChoiceId(raw);
+      if (!id) return false;
+      return evalChoicePred(id, predicate.pred);
+    }
+    case "multi": {
+      const ids = normalizeChoiceIds(raw);
+      if (!ids) return false;
+      return evalMultiPred(ids, predicate.pred);
+    }
+    case "boolean": {
+      const b = normalizeBoolean(raw);
+      if (b === void 0) return false;
+      return evalBooleanPred(b, predicate.pred);
+    }
+    default:
+      return false;
+  }
+};
+var evaluateDecisionNode = (node, ctx) => {
+  for (const c of node.cases) {
+    if (evaluateDecisionExpression(c.expression, ctx)) {
+      return {
+        matchedCaseId: c.id,
+        next: c.next,
+        clauseDigest: digestDecisionExpression(c.expression)
+      };
+    }
+  }
+  return {
+    matchedCaseId: null,
+    next: node.elseNext,
+    clauseDigest: "else"
+  };
+};
+
+// src/stateMachine/graphLanding.ts
+var resolveOsPermissionDestination = (screen, response) => {
+  const layer = findLayerById(screen, response.layerId);
+  if (!layer || layer.kind !== "button" || layer.action.kind !== "request_os_permission")
+    return null;
+  if (layer.action.permissionKey !== response.permissionKey) return null;
+  const target = layer.action.outcomes[response.outcome];
+  if (target === OS_PERMISSION_OUTCOME_END) return null;
+  if (target === OS_PERMISSION_OUTCOME_CONTINUE) return screen.next.default ?? null;
+  return target;
+};
+var resolveNextScreenId = (screen, response) => {
+  if (response.kind === "screen_commit") {
+    return resolveNextScreenId(screen, response.primary);
+  }
+  if (response.kind === "go_to_screen") return response.screenId;
+  if (response.kind === "permission_outcome") {
+    const nextId = resolveOsPermissionDestination(screen, response);
+    return nextId ?? screen.next.default ?? null;
+  }
+  if (response.kind === "app_review_outcome") {
+    const layer = findLayerById(screen, response.layerId);
+    if (!layer || layer.kind !== "button" || layer.action.kind !== "request_app_review") {
+      return screen.next.default ?? null;
+    }
+    return screen.next.default ?? null;
+  }
+  if (response.kind === "oauth_login_resolve") {
+    return screen.next.default ?? null;
+  }
+  if (response.kind === "email_password_auth_resolve") {
+    return screen.next.default ?? null;
+  }
+  const input = findInputLayer(screen);
+  if (input && (input.kind === "single_choice" || input.kind === "multiple_choice") && input.branching.enabled) {
+    if (response.kind === "choice") {
+      const m = input.branching.conditions.find((c) => c.choiceId === response.choiceId);
+      if (m) return m.goTo;
+    } else if (response.kind === "multiChoice") {
+      const m = input.branching.conditions.find((c) => response.choiceIds.includes(c.choiceId));
+      if (m) return m.goTo;
+    }
+  }
+  return screen.next.default ?? null;
+};
+var resolveThroughGraph = (manifest, cursor, responses, session, onDecisionEvaluated) => {
+  let cur = cursor;
+  const evalCtx = {
+    locale: session.locale,
+    platform: session.platform,
+    sdkAttributes: session.sdkAttributes,
+    responses
+  };
+  while (cur) {
+    const dn = findDecisionNode(manifest, cur);
+    if (!dn) break;
+    const evalResult = evaluateDecisionNode(dn, evalCtx);
+    onDecisionEvaluated?.({
+      decisionNodeId: dn.id,
+      matchedCaseId: evalResult.matchedCaseId,
+      clauseDigest: evalResult.clauseDigest
+    });
+    cur = evalResult.next;
+    if (cur == null) break;
+  }
+  if (cur == null) return { kind: "end" };
+  if (findExternalSurface(manifest, cur)) return { kind: "surface", nodeId: cur };
+  return { kind: "screen", screenId: cur };
+};
+var responseKeyFor = (screen, response) => {
+  if (response.kind === "text" || response.kind === "choice" || response.kind === "multiChoice" || response.kind === "scale" || response.kind === "checkbox") {
+    const input = findInputLayer(screen);
+    if (input) return input.fieldKey;
+  }
+  if (response.kind === "permission_outcome") return permissionCaptureFieldKey(response.permissionKey);
+  if (response.kind === "app_review_outcome") return appReviewCaptureFieldKey(response.layerId);
+  if (response.kind === "checkbox") return response.fieldKey;
+  if (response.kind === "oauth_login_resolve") return oauthLoginResponseKey(response.layerId);
+  if (response.kind === "email_password_auth_resolve") {
+    return emailPasswordAuthResponseKey(response.layerId);
+  }
+  return screen.id;
+};
+var applyGraphLanding = (base, landing, nextResponses, now) => {
+  if (landing.kind === "end") {
+    return {
+      ...base,
+      responses: nextResponses,
+      currentScreenId: null,
+      pendingExternalSurface: null,
+      status: "completed",
+      completedAt: now
+    };
+  }
+  if (landing.kind === "surface") {
+    return {
+      ...base,
+      responses: nextResponses,
+      currentScreenId: null,
+      pendingExternalSurface: { nodeId: landing.nodeId },
+      history: [...base.history, landing.nodeId]
+    };
+  }
+  return {
+    ...base,
+    responses: nextResponses,
+    currentScreenId: landing.screenId,
+    pendingExternalSurface: null,
+    history: [...base.history, landing.screenId]
+  };
+};
+var startFlow = (state, second) => {
+  const opts = typeof second === "string" ? { now: second } : second ?? {};
+  const now = opts.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const entry = state.manifest.entryScreenId;
+  if (entry == null) {
+    return {
+      ...state,
+      status: "idle",
+      currentScreenId: null,
+      pendingExternalSurface: null,
+      history: [],
+      startedAt: null,
+      completedAt: null
+    };
+  }
+  const landing = resolveThroughGraph(
+    state.manifest,
+    entry,
+    {},
+    {
+      ...state.session
+    },
+    opts.onDecisionEvaluated
+  );
+  if (landing.kind === "end") {
+    return {
+      ...state,
+      status: "completed",
+      currentScreenId: null,
+      pendingExternalSurface: null,
+      history: [entry],
+      startedAt: now,
+      completedAt: now
+    };
+  }
+  if (landing.kind === "surface") {
+    return {
+      ...state,
+      status: "running",
+      currentScreenId: null,
+      pendingExternalSurface: { nodeId: landing.nodeId },
+      history: [landing.nodeId],
+      startedAt: now
+    };
+  }
+  return {
+    ...state,
+    status: "running",
+    currentScreenId: landing.screenId,
+    pendingExternalSurface: null,
+    history: [landing.screenId],
+    startedAt: now
+  };
+};
+var submitResponse = (state, response, third) => {
+  const opts = typeof third === "string" ? { now: third } : third ?? {};
+  const now = opts.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  if (state.status !== "running") return state;
+  if (response.kind === "external_surface_outcome") {
+    const pending = state.pendingExternalSurface;
+    if (!pending || pending.nodeId !== response.nodeId) return state;
+    const surface = findExternalSurface(state.manifest, pending.nodeId);
+    if (!surface) return state;
+    const nextSession = response.sdkKeyPatch ? {
+      ...state.session,
+      sdkAttributes: { ...state.session.sdkAttributes, ...response.sdkKeyPatch }
+    } : state.session;
+    const target = surface.outcomes[response.outcome] ?? surface.fallback;
+    const nextResponses2 = {
+      ...state.responses,
+      [externalSurfaceResponseKey(pending.nodeId)]: response
+    };
+    if (target === EXTERNAL_SURFACE_NO_NEXT) {
+      return {
+        ...state,
+        session: nextSession,
+        responses: nextResponses2,
+        pendingExternalSurface: null,
+        currentScreenId: null,
+        status: "completed",
+        completedAt: now
+      };
+    }
+    const landing2 = resolveThroughGraph(
+      state.manifest,
+      target,
+      nextResponses2,
+      nextSession,
+      opts.onDecisionEvaluated
+    );
+    return applyGraphLanding(
+      { ...state, session: nextSession },
+      landing2,
+      nextResponses2,
+      now
+    );
+  }
+  if (!state.currentScreenId) return state;
+  const screen = findScreen(state.manifest, state.currentScreenId);
+  if (!screen) return state;
+  if (response.kind === "screen_commit") {
+    const mergedResponses = { ...state.responses };
+    for (const [fk, value] of Object.entries(response.checkboxValues)) {
+      mergedResponses[fk] = { kind: "checkbox", fieldKey: fk, value };
+    }
+    if (response.capturedDraft) {
+      mergedResponses[responseKeyFor(screen, response.capturedDraft)] = response.capturedDraft;
+    }
+    return submitResponse({ ...state, responses: mergedResponses }, response.primary, opts);
+  }
+  if (response.kind === "go_back") {
+    const fallback = response.fallbackScreenId;
+    if (state.history.length > 1) {
+      const nextHistory = state.history.slice(0, -1);
+      const prevId = nextHistory[nextHistory.length - 1];
+      if (!prevId) return state;
+      return {
+        ...state,
+        currentScreenId: prevId,
+        history: nextHistory
+      };
+    }
+    if (fallback && findScreen(state.manifest, fallback)) {
+      return {
+        ...state,
+        currentScreenId: fallback,
+        history: [fallback]
+      };
+    }
+    return state;
+  }
+  if (response.kind === "oauth_login_resolve" && !response.success) {
+    const key2 = oauthLoginResponseKey(response.layerId);
+    return {
+      ...state,
+      responses: { ...state.responses, [key2]: response }
+    };
+  }
+  if (response.kind === "email_password_auth_resolve" && !response.success) {
+    const key2 = emailPasswordAuthResponseKey(response.layerId);
+    return {
+      ...state,
+      responses: { ...state.responses, [key2]: response }
+    };
+  }
+  if (response.kind === "end_flow") {
+    const nextResponses2 = { ...state.responses };
+    if (response.consumedDraft) {
+      nextResponses2[responseKeyFor(screen, response.consumedDraft)] = response.consumedDraft;
+    }
+    nextResponses2[responseKeyFor(screen, { kind: "end_flow" })] = { kind: "end_flow" };
+    return {
+      ...state,
+      responses: nextResponses2,
+      currentScreenId: null,
+      status: "completed",
+      completedAt: now
+    };
+  }
+  if (response.kind === "skip") {
+    const nextResponses2 = { ...state.responses };
+    const manualInput = findManualSubmitInputLayer(screen);
+    if (manualInput) {
+      nextResponses2[manualInput.fieldKey] = { kind: "bypass_input", via: "skip" };
+    }
+    nextResponses2[responseKeyFor(screen, { kind: "skip" })] = { kind: "skip" };
+    const nextRaw2 = resolveNextScreenId(screen, { kind: "skip" });
+    const landing2 = resolveThroughGraph(
+      state.manifest,
+      nextRaw2,
+      nextResponses2,
+      state.session,
+      opts.onDecisionEvaluated
+    );
+    return applyGraphLanding(state, landing2, nextResponses2, now);
+  }
+  const key = responseKeyFor(screen, response);
+  const nextResponses = { ...state.responses, [key]: response };
+  if (response.kind === "go_to_screen") {
+    const manualInput = findManualSubmitInputLayer(screen);
+    if (manualInput) {
+      nextResponses[manualInput.fieldKey] = { kind: "bypass_input", via: "go_to_screen" };
+    }
+  }
+  const nextRaw = resolveNextScreenId(screen, response);
+  const landing = resolveThroughGraph(
+    state.manifest,
+    nextRaw,
+    nextResponses,
+    state.session,
+    opts.onDecisionEvaluated
+  );
+  return applyGraphLanding(state, landing, nextResponses, now);
+};
+
+// src/stateMachine/flowTerminal.ts
+var TERMINAL_EXPORT_AUTH_RESPONSE_KEY_PREFIXES = ["oauth:", "email_pw:"];
+var isAuthTerminalExportResponseKey = (key) => TERMINAL_EXPORT_AUTH_RESPONSE_KEY_PREFIXES.some((prefix) => key.startsWith(prefix));
+var stripAuthResponsesForTerminalExport = (responses) => {
+  const out = {};
+  for (const [k, v] of Object.entries(responses)) {
+    if (isAuthTerminalExportResponseKey(k)) continue;
+    out[k] = v;
+  }
+  return out;
+};
+var stepResponseToCompletionValue = (r) => {
+  if (r.kind === "screen_commit") return void 0;
+  switch (r.kind) {
+    case "choice":
+      return r.choiceId;
+    case "multiChoice":
+      return r.choiceIds;
+    case "text":
+      return { value: r.value, classification: r.classification };
+    case "scale":
+      return r.value;
+    case "checkbox":
+      return r.value;
+    case "cta":
+      return r.action;
+    case "carousel":
+      return "carousel";
+    case "end_flow":
+      return "end_flow";
+    case "skip":
+      return "skip";
+    case "permission_outcome":
+      return r.outcome;
+    case "app_review_outcome":
+      return r.outcome;
+    case "oauth_login_resolve":
+      return {
+        success: r.success,
+        customerExternalId: r.customerExternalId,
+        provider: r.provider
+      };
+    case "email_password_auth_resolve":
+      return {
+        success: r.success,
+        mode: r.mode,
+        email: r.email
+      };
+    case "bypass_input":
+      return { bypassed: true, via: r.via };
+    case "external_surface_outcome":
+      return { outcome: r.outcome };
+    case "go_to_screen":
+      return { goToScreen: r.screenId };
+    case "go_back":
+      return void 0;
+    default: {
+      const _never = r;
+      return _never;
+    }
+  }
+};
+var buildCompletionResponses = (state) => {
+  const out = {};
+  for (const [key, r] of Object.entries(state.responses)) {
+    const v = stepResponseToCompletionValue(r);
+    if (v !== void 0) out[key] = v;
+  }
+  return out;
+};
+var abandonFlow = (state, now = (/* @__PURE__ */ new Date()).toISOString()) => ({
+  ...state,
+  status: "abandoned",
+  completedAt: now
+});
+
+export { abandonFlow, applyGraphLanding, buildCompletionResponses, externalSurfaceResponseKey, findExternalSurface, findScreen, initFlowState, isAuthTerminalExportResponseKey, isEligibleConsumedDraft, resolveNextScreenId, resolveThroughGraph, responseKeyFor, startFlow, stepResponseToCompletionValue, stripAuthResponsesForTerminalExport, submitResponse };
+//# sourceMappingURL=stateMachine.js.map
+//# sourceMappingURL=stateMachine.js.map