@gravity-rail/sdk 0.14.0 → 0.16.0

package/dist/index.js

@@ -65,6 +65,7 @@ import {
   PIDS_SOURCES,
   POSITIVE_RATING_THRESHOLD,
   ProductType,
+  PromoCodeStatus,
   QUERY_VALUELESS_OPS,
   QueriesApi,
   REALTIME_MODEL_CUSTOM,
@@ -98,6 +99,7 @@ import {
   TemplatesApi,
   ToolkitState,
   WIDGET_SLUGS,
+  WORKFLOW_IMPLICIT_USE_SCOPE,
   WorkflowAccessWarningResourceType,
   WorkspaceFeature,
   WorkspaceProvisionStatus,
@@ -131,9 +133,12 @@ import {
   isRegistryInitialized,
   isSMSDeliveryFailureStatus,
   requiresAssistantParticipant,
+  roleCanUseWorkflow,
+  roleImplicitWorkflowUseScope,
+  roleWorkflowAccess,
   usesBuiltinAssistant,
   validateFeatureDependencies
-} from "./chunk-K4MDFGMO.js";
+} from "./chunk-4B7T6MBH.js";
 import {
   AttendeeResponseStatus,
   AttendeeStatus,
@@ -148,7 +153,7 @@ import {
   DataSensitivity,
   DataTypeRecordScope,
   IndexStatus
-} from "./chunk-V7ZKEH4V.js";
+} from "./chunk-2YLKG4TT.js";
 import {
   ApiError,
   BaseApiClient,
@@ -191,6 +196,14 @@ var WorkspaceBuilderResource = class {
     }
     return this._uuid;
   }
+  /**
+   * True for resources the server creates on our behalf (currently a
+   * journey's `Start` step). They are kept in the resource list so edges can
+   * reference them, but they are never created, printed, or counted.
+   */
+  get isImplicit() {
+    return false;
+  }
   matchKey() {
     return void 0;
   }
@@ -213,6 +226,19 @@ function resolveRefValue(value) {
   }
   return out;
 }
+function resolveIdRefs(value) {
+  return resolveIdRefValue(value);
+}
+function resolveIdRefValue(value) {
+  if (value instanceof WorkspaceBuilderResource) return value.id;
+  if (Array.isArray(value)) return value.map(resolveIdRefValue);
+  if (!isPlainRecord(value)) return value;
+  const out = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    out[key] = resolveIdRefValue(nestedValue);
+  }
+  return out;
+}
 
 // src/workspace-builder/automation.ts
 var MemberFilterBuilder = class extends WorkspaceBuilderResource {
@@ -226,7 +252,12 @@ var MemberFilterBuilder = class extends WorkspaceBuilderResource {
   description;
   /** Query-engine predicate (JSON IR) authored on MemberFilter.query. */
   query = null;
-  /** Set the filter's query-engine predicate (JSON IR). */
+  /**
+   * Set the filter's query-engine predicate (JSON IR).
+   *
+   * Anywhere the IR wants a numeric id you may pass the builder that will own
+   * it (e.g. a label in a `member.labelId` value); refs resolve at apply time.
+   */
   setQuery(query) {
     this.query = query;
     return this;
@@ -235,10 +266,12 @@ var MemberFilterBuilder = class extends WorkspaceBuilderResource {
     return `MemberFilter: ${this.name}${this.query ? " (query)" : ""}`;
   }
   async apply(client) {
+    if (this._existed) return;
     const payload = {
       name: this.name,
       description: this.description,
-      query: this.query
+      // Builder refs inside the IR become ids here; see resolveIdRefs.
+      query: resolveIdRefs(this.query)
     };
     const result = await client.createMemberFilter(payload);
     this._id = result.id;
@@ -533,35 +566,134 @@ var MemberLabelBuilder = class extends WorkspaceBuilderResource {
 };
 
 // src/workspace-builder/journeys.ts
+var SECONDS_PER_DAY = 86400;
+function edgeKey(parentId, childId) {
+  return `${parentId}:${childId}`;
+}
+function edgeCondition(options) {
+  const clauses = [];
+  if (options.afterDays !== void 0) {
+    clauses.push(`days_since(parent_step.completed_at) >= ${options.afterDays}`);
+  }
+  if (options.when) clauses.push(`(${options.when})`);
+  if (!clauses.length) return void 0;
+  return clauses.join(" && ");
+}
 var JourneyStepBuilder = class extends WorkspaceBuilderResource {
   // journey-decoupling Phase 7: a Journey step no longer links to a Workflow.
   // A step nudges via EventRule actions instead of running a Workflow, so the
   // builder no longer accepts or emits a workflow reference.
-  constructor(name, journey, order = 0, description = "") {
+  constructor(name, journey, order = 0, description = "", options = {}) {
     super();
     this.name = name;
     this.journey = journey;
     this.order = order;
     this.description = description;
+    this.assigneeId = options.assigneeId;
+    this.posX = options.posX;
+    this.posY = options.posY;
   }
   name;
   journey;
   order;
   description;
   connections = [];
-  connectsTo(child, condition, required = false, timeoutSeconds) {
-    this.connections.push({ parent: this, child, condition, required, timeoutSeconds });
+  rules = [];
+  assigneeId;
+  posX;
+  posY;
+  /** Wire an edge to `child` and return the CHILD, so chains read linearly. */
+  connectsTo(child, options = {}) {
+    if (child === this) {
+      throw new Error(`Journey step '${this.name}' cannot connect to itself`);
+    }
+    const abandonSeconds = options.abandonAfterDays !== void 0 ? options.abandonAfterDays * SECONDS_PER_DAY : options.timeoutSeconds;
+    this.connections.push({
+      parent: this,
+      child,
+      condition: edgeCondition(options),
+      required: options.required ?? false,
+      timeoutSeconds: abandonSeconds,
+      order: options.order,
+      filterId: options.filterId
+    });
+    return child;
+  }
+  /**
+   * Attach a `JOURNEY_STEP_EXECUTE` action — what this step actually DOES
+   * when a member reaches it. A step with no rules is inert: the member
+   * lands on it, nothing is sent, and the journey moves on.
+   */
+  onExecute(actionType, params = {}, options = {}) {
+    this.rules.push({
+      uuid: crypto.randomUUID(),
+      actionType,
+      actionParams: params,
+      options
+    });
     return this;
   }
+  /**
+   * Text the member. `phoneNumberUUID` is a workspace PhoneNumber with SMS
+   * enabled. Pass `workflowUUID` to start an SMS workflow chat, or
+   * `messageTemplate` for a one-off send.
+   */
+  sendsSms(params, options = {}) {
+    return this.onExecute("sms:send" /* SMS_SEND */, params, options);
+  }
+  /**
+   * Call the member. Both the workspace PhoneNumber uuid (voice enabled) and
+   * the Workflow uuid that drives the call are required.
+   */
+  callsMember(params, options = {}) {
+    return this.onExecute("phone:call" /* PHONE_CALL */, params, options);
+  }
+  /** Email the member from a workspace inbox. */
+  sendsEmail(params, options = {}) {
+    return this.onExecute("email:send" /* EMAIL_SEND */, params, options);
+  }
+  /** Label the member on arrival — pass label builders, not ids. */
+  addsLabels(labels, options = {}) {
+    return this.onExecute(
+      "member:label" /* MEMBER_LABEL_ACTION */,
+      { addLabelIds: labels },
+      options
+    );
+  }
+  /** True once this step has something to do when a member reaches it. */
+  get hasOutreach() {
+    return this.rules.length > 0;
+  }
+  eventRuleInputs() {
+    return this.rules.map((rule) => ({
+      uuid: rule.uuid,
+      eventType: "journey_step:execute" /* JOURNEY_STEP_EXECUTE */,
+      actionType: rule.actionType,
+      actionParams: resolveRefs(rule.actionParams),
+      ...rule.options.name ? { name: rule.options.name } : {},
+      ...rule.options.when ? { conditions: rule.options.when } : {},
+      ...rule.options.delaySeconds ? { delay: rule.options.delaySeconds } : {},
+      active: rule.options.active ?? true
+    }));
+  }
   planLine() {
-    return `Step: ${this.name}`;
+    const actions = this.rules.map((rule) => rule.actionType).join(" + ");
+    return `Step: ${this.name}${actions ? ` (${actions})` : ""}`;
   }
   async apply(client) {
+    if (this._existed) return;
     if (this.journey._id === void 0) return;
+    const rules = this.eventRuleInputs();
     const payload = {
       name: this.name,
       description: this.description,
-      order: this.order
+      order: this.order,
+      ...this.assigneeId !== void 0 ? { assigneeId: this.assigneeId } : {},
+      ...this.posX !== void 0 ? { posX: this.posX } : {},
+      ...this.posY !== void 0 ? { posY: this.posY } : {},
+      // Saved atomically with the step, so a partial failure cannot leave
+      // an inert step behind.
+      ...rules.length ? { eventRules: rules } : {}
     };
     const result = await client.createStep(this.journey._id, payload);
     this._id = result.id;
@@ -569,26 +701,59 @@ var JourneyStepBuilder = class extends WorkspaceBuilderResource {
     this._created = true;
   }
 };
+var StartStepBuilder = class extends JourneyStepBuilder {
+  get isImplicit() {
+    return true;
+  }
+  planLine() {
+    return "Step: Start (auto-created)";
+  }
+  async apply() {
+  }
+};
 var JourneyBuilder = class extends WorkspaceBuilderResource {
   constructor(name, options = {}) {
     super();
     this.name = name;
     this.description = options.description ?? "";
+    this.start = new StartStepBuilder("Start", this, 0);
+    this.steps.push(this.start);
   }
   name;
   description;
   steps = [];
   goals = [];
+  /** The auto-created `Start` step — connect the first real step to it. */
+  start;
+  /** `parentId:childId` for every edge the server already has (see `adopt`). */
+  existingEdges = /* @__PURE__ */ new Set();
   step(name, options = {}) {
     const step = new JourneyStepBuilder(
       name,
       this,
-      options.order ?? 0,
-      options.description ?? ""
+      options.order ?? this.steps.length,
+      options.description ?? "",
+      options
     );
     this.steps.push(step);
     return step;
   }
+  /**
+   * Declare a linear cadence: `Start → steps[0] → steps[1] → …`, each edge
+   * carrying the matching entry from `spacing`.
+   *
+   * Chaining is not optional polish. A step created with no incoming edge is
+   * a ROOT, and every root fires the moment a member enrols — a "three
+   * follow-ups over four days" journey built without edges sends all three
+   * at once.
+   */
+  sequence(steps, spacing = []) {
+    let parent = this.start;
+    steps.forEach((step, index) => {
+      parent = parent.connectsTo(step, spacing[index] ?? {});
+    });
+    return this;
+  }
   goal(name, options = {}) {
     this.goals.push({
       name,
@@ -596,17 +761,85 @@ var JourneyBuilder = class extends WorkspaceBuilderResource {
       step: options.step,
       completionCel: options.completionCel ?? options.completion_cel,
       value: options.value,
-      order: options.order ?? 0
+      order: options.order ?? this.goals.length
     });
     return this;
   }
+  /**
+   * Authoring problems that make a journey silently misbehave at runtime.
+   * Reported at plan/preview time, before anything is written.
+   */
+  validate() {
+    const problems = [];
+    const withParents = /* @__PURE__ */ new Set();
+    for (const step of this.steps) {
+      for (const connection of step.connections) withParents.add(connection.child);
+    }
+    for (const step of this.steps) {
+      if (step === this.start) continue;
+      if (!withParents.has(step)) {
+        problems.push(
+          `step '${step.name}' has no incoming edge \u2014 it is a root and fires for every member the moment they enrol. Connect it from journey.start or a prior step.`
+        );
+      }
+      if (!step.hasOutreach) {
+        problems.push(
+          `step '${step.name}' has no JOURNEY_STEP_EXECUTE action \u2014 a member reaching it gets nothing. Add one with .sendsSms / .callsMember / .sendsEmail / .onExecute.`
+        );
+      }
+    }
+    if (!this.goals.length) {
+      problems.push(`journey '${this.name}' has no goals \u2014 nothing measures whether it works.`);
+    }
+    return problems;
+  }
+  /**
+   * Adopt an existing journey, its steps, and its EDGES, matched by name.
+   *
+   * Re-running a builder script is normal — a program is usually built in
+   * stages as provisioning lands — and without adoption the second run would
+   * create a duplicate journey and a duplicate set of steps beside the live
+   * one, with members enrolled in neither.
+   *
+   * The edge set is recorded from the server's own `childConnections` rather
+   * than inferred from "both steps exist". A first run that created the steps
+   * and then failed before writing an edge leaves exactly that state, and
+   * inferring would skip the missing edge on every subsequent run — leaving a
+   * permanent root step that fires for every member at enrolment, silently.
+   * The journey detail read eager-loads connections, so the real answer is
+   * already in hand; there is no reason to guess.
+   */
+  adopt(existing) {
+    super.adopt(existing);
+    const existingSteps = existing.steps ?? [];
+    const byName = new Map(existingSteps.map((step) => [step.name, step]));
+    const startStep = existingSteps.find((step) => step.id === existing.startStepId) ?? byName.get("Start");
+    if (startStep) this.start.adopt(startStep);
+    for (const step of this.steps) {
+      if (step === this.start) continue;
+      const match = byName.get(step.name);
+      if (match) step.adopt(match);
+    }
+    for (const step of existingSteps) {
+      for (const edge of step.childConnections ?? []) {
+        this.existingEdges.add(edgeKey(edge.parentStepId, edge.childStepId));
+      }
+    }
+  }
+  /** True when the server already has this exact edge. */
+  hasEdge(parent, child) {
+    if (parent._id === void 0 || child._id === void 0) return false;
+    return this.existingEdges.has(edgeKey(parent._id, child._id));
+  }
   planLine() {
     const parts = [];
-    if (this.steps.length) parts.push(`${this.steps.length} steps`);
+    const real = this.steps.filter((step) => step !== this.start);
+    if (real.length) parts.push(`${real.length} steps`);
     if (this.goals.length) parts.push(`${this.goals.length} goals`);
     return `Journey: ${this.name}${parts.length ? ` (${parts.join(", ")})` : ""}`;
   }
   async apply(client) {
+    if (this._existed) return;
     const result = await client.createJourney({
       name: this.name,
       description: this.description
@@ -614,6 +847,15 @@ var JourneyBuilder = class extends WorkspaceBuilderResource {
     this._id = result.id;
     this._uuid = result.uuid;
     this._created = true;
+    const startStep = (result.steps ?? []).find(
+      (step) => step.id === result.startStepId || step.name === "Start"
+    );
+    if (!startStep) {
+      throw new Error(
+        `Journey '${this.name}' was created without a Start step; edges from journey.start cannot be wired.`
+      );
+    }
+    this.start.adopt(startStep);
   }
 };
 function buildJourneyConnectionPayload(connection) {
@@ -623,7 +865,9 @@ function buildJourneyConnectionPayload(connection) {
     childStepUuid: connection.child._uuid,
     ...connection.condition ? { celCondition: connection.condition } : {},
     ...connection.required ? { required: true } : {},
-    ...connection.timeoutSeconds ? { timeoutSeconds: connection.timeoutSeconds } : {}
+    ...connection.timeoutSeconds ? { timeoutSeconds: connection.timeoutSeconds } : {},
+    ...connection.order !== void 0 ? { order: connection.order } : {},
+    ...connection.filterId !== void 0 ? { filterId: connection.filterId } : {}
   };
 }
 function buildJourneyGoalPayload(goal) {
@@ -909,6 +1153,15 @@ var PHASES = /* @__PURE__ */ new Map([
   [JourneyBuilder, 7],
   [JourneyStepBuilder, 8]
 ]);
+function phaseFor(resource) {
+  let ctor = resource.constructor;
+  while (ctor) {
+    const phase = PHASES.get(ctor);
+    if (phase !== void 0) return phase;
+    ctor = Object.getPrototypeOf(ctor);
+  }
+  return 99;
+}
 var WorkspaceBuilder = class {
   constructor(client) {
     this.client = client;
@@ -971,7 +1224,8 @@ var WorkspaceBuilder = class {
 ${"=".repeat(50)}`);
     writeLine("Plan");
     writeLine("=".repeat(50));
-    for (const resource of resources) {
+    const declared = resources.filter((resource) => !resource.isImplicit);
+    for (const resource of declared) {
       writeLine(`  + ${resource.planLine()}`);
     }
     const wiring = this.collectWiringSummary(resources);
@@ -979,8 +1233,9 @@ ${"=".repeat(50)}`);
       writeLine("\n  Wiring:");
       for (const line of wiring) writeLine(`    ${line}`);
     }
+    this.reportJourneyWarnings();
     writeLine(`
-  Total: ${resources.length} resources, ${wiring.length} connections`);
+  Total: ${declared.length} resources, ${wiring.length} connections`);
     writeLine(`${"=".repeat(50)}
 `);
   }
@@ -991,7 +1246,8 @@ ${"=".repeat(50)}`);
 ${"=".repeat(50)}`);
     writeLine("Preview");
     writeLine("=".repeat(50));
-    for (const resource of resources) {
+    const declared = resources.filter((resource) => !resource.isImplicit);
+    for (const resource of declared) {
       if (resource._existed) {
         writeLine(`  = ${resource.planLine()} (exists, id=${resource._id})`);
       } else {
@@ -1003,8 +1259,9 @@ ${"=".repeat(50)}`);
       writeLine("\n  Wiring:");
       for (const line of wiring) writeLine(`    ${line}`);
     }
-    const toCreate = resources.filter((resource) => !resource._existed);
-    const existing = resources.filter((resource) => resource._existed);
+    this.reportJourneyWarnings();
+    const toCreate = declared.filter((resource) => !resource._existed);
+    const existing = declared.filter((resource) => resource._existed);
     writeLine(
       `
   Total: ${toCreate.length} to create, ${existing.length} existing, ${wiring.length} connections`
@@ -1012,6 +1269,18 @@ ${"=".repeat(50)}`);
     writeLine(`${"=".repeat(50)}
 `);
   }
+  /**
+   * Print journey authoring problems that only bite at runtime — a step with
+   * no incoming edge fires for every member at enrolment, and a step with no
+   * action does nothing at all. Both look fine in the editor, so they are
+   * surfaced before the write rather than discovered from a member's phone.
+   */
+  reportJourneyWarnings() {
+    const problems = this.resources.filter((resource) => resource instanceof JourneyBuilder).flatMap((journey) => journey.validate());
+    if (!problems.length) return;
+    writeLine("\n  Journey warnings:");
+    for (const problem of problems) writeLine(`    ! ${problem}`);
+  }
   async apply() {
     const resources = this.sortedResources();
     await this.resolveExisting(resources);
@@ -1019,6 +1288,7 @@ ${"=".repeat(50)}`);
     writeLine("Applying...");
     for (const resource of resources) {
       try {
+        if (resource.isImplicit) continue;
         if (resource._existed) {
           const key = resourceKey(resource);
           summary[key] ??= [];
@@ -1076,6 +1346,29 @@ Done! Created ${count} resources.`);
         }
       }
     }
+    const filterNames = new Map(
+      resources.filter(
+        (resource) => resource instanceof MemberFilterBuilder
+      ).map((resource) => [resource.name, resource])
+    );
+    if (filterNames.size) {
+      for (const existing of await this.client.getMemberFilters()) {
+        if (existing.name && filterNames.has(existing.name)) {
+          filterNames.get(existing.name).adopt(existing);
+        }
+      }
+    }
+    const journeyNames = new Map(
+      resources.filter((resource) => resource instanceof JourneyBuilder).map((resource) => [resource.name, resource])
+    );
+    if (journeyNames.size) {
+      const existingJourneys = await this.client.getJourneys();
+      for (const existing of existingJourneys.items) {
+        if (!existing.name || !journeyNames.has(existing.name)) continue;
+        const detail = await this.client.getJourney(existing.id);
+        journeyNames.get(existing.name).adopt(detail);
+      }
+    }
     if (!workflowNames.size) return;
     const existingWorkflows = await this.client.getWorkflows();
     for (const { workflow: existing } of existingWorkflows.items) {
@@ -1126,9 +1419,7 @@ Done! Created ${count} resources.`);
         all.push(...resource.steps);
       }
     }
-    return all.sort(
-      (a, b) => (PHASES.get(a.constructor) ?? 99) - (PHASES.get(b.constructor) ?? 99)
-    );
+    return all.sort((a, b) => phaseFor(a) - phaseFor(b));
   }
   collectWiringSummary(resources) {
     const lines = [];
@@ -1149,7 +1440,11 @@ Done! Created ${count} resources.`);
           lines.push(`${rule.actionType} rule on '${resource.name}'`);
       } else if (resource instanceof JourneyStepBuilder) {
         for (const connection of resource.connections) {
-          lines.push(`${connection.parent.name} -> ${connection.child.name}`);
+          const guard = connection.condition ? ` [${connection.condition}]` : "";
+          lines.push(`${connection.parent.name} -> ${connection.child.name}${guard}`);
+        }
+        for (const rule of resource.rules) {
+          lines.push(`${rule.actionType} on step '${resource.name}'`);
         }
       } else if (resource instanceof JourneyBuilder) {
         for (const goal of resource.goals) lines.push(`Goal: ${goal.name}`);
@@ -1265,6 +1560,10 @@ Done! Created ${count} resources.`);
       if (!(resource instanceof JourneyStepBuilder)) continue;
       for (const connection of resource.connections) {
         if (resource.journey._id === void 0) continue;
+        if (resource.journey.hasEdge(connection.parent, connection.child)) {
+          writeLine(`  Exists: ${connection.parent.name} -> ${connection.child.name}`);
+          continue;
+        }
         const payload = buildJourneyConnectionPayload(connection);
         if (!payload) continue;
         await this.client.createConnection(resource.journey._id, payload);
@@ -1275,6 +1574,12 @@ Done! Created ${count} resources.`);
   async applyJourneyGoals(resources) {
     for (const resource of resources) {
       if (!(resource instanceof JourneyBuilder) || resource._id === void 0) continue;
+      if (resource._existed) {
+        for (const goal of resource.goals) {
+          writeLine(`  Skipped (journey already exists): Goal: ${goal.name}`);
+        }
+        continue;
+      }
       for (const goal of resource.goals) {
         await this.client.createGoal(resource._id, buildJourneyGoalPayload(goal));
         writeLine(`  Created goal: ${goal.name}`);
@@ -1575,6 +1880,7 @@ export {
   PIDS_SOURCES,
   POSITIVE_RATING_THRESHOLD,
   ProductType,
+  PromoCodeStatus,
   QUERY_VALUELESS_OPS,
   QueriesApi,
   REALTIME_MODEL_CUSTOM,
@@ -1611,10 +1917,12 @@ export {
   TemplatesApi,
   ToolkitState,
   WIDGET_SLUGS,
+  WORKFLOW_IMPLICIT_USE_SCOPE,
   WorkflowAccessWarningResourceType,
   WorkflowBuilder,
   WorkflowAccessWarningResourceType as WorkflowResourceType,
   WorkspaceBuilder,
+  WorkspaceBuilderResource,
   WorkspaceFeature,
   WorkspaceProvisionStatus,
   areDependenciesSatisfied,
@@ -1649,6 +1957,9 @@ export {
   isSMSDeliveryFailureStatus,
   parseOrgAuthChallenge,
   requiresAssistantParticipant,
+  roleCanUseWorkflow,
+  roleImplicitWorkflowUseScope,
+  roleWorkflowAccess,
   runWorkspaceScript,
   usesBuiltinAssistant,
   validateFeatureDependencies