@drip-apex/sdk 0.1.0 → 0.3.0

package/src/editor/view.test.ts

@@ -160,6 +160,56 @@ describe("editor view v2", () => {
     cleanup();
   });
 
+  it("renders saved-but-pending as a warning instead of saved or failed", () => {
+    const controller = makeController(
+      state({
+        saveState: "pending",
+        saveMessage: "Saved, but publication is pending.",
+      }),
+    );
+    const { shadow, cleanup } = mount(controller);
+
+    const chip = shadow.querySelector(".save-chip");
+    expect(chip?.classList.contains("pending")).toBe(true);
+    expect(chip?.textContent).toContain("Saved — publication pending");
+    expect(chip?.classList.contains("saved")).toBe(false);
+    expect(chip?.classList.contains("failed")).toBe(false);
+    cleanup();
+  });
+
+  it("renders a soft publication warning separately from full success", () => {
+    const controller = makeController(
+      state({
+        saveState: "warning",
+        saveMessage: "Saved and published, but one publication step is incomplete.",
+      }),
+    );
+    const { shadow, cleanup } = mount(controller);
+
+    const chip = shadow.querySelector(".save-chip");
+    expect(chip?.classList.contains("warning")).toBe(true);
+    expect(chip?.textContent).toContain("Saved — publication warning");
+    expect(chip?.classList.contains("saved")).toBe(false);
+    cleanup();
+  });
+
+  it("renders committed publication failure separately from a save failure", () => {
+    const controller = makeController(
+      state({
+        saveState: "publication_failed",
+        saveMessage: "Saved, but storefront publication failed.",
+      }),
+    );
+    const { shadow, cleanup } = mount(controller);
+
+    const chip = shadow.querySelector(".save-chip");
+    expect(chip?.classList.contains("publication-failed")).toBe(true);
+    expect(chip?.textContent).toContain("Saved — publication failed");
+    expect(chip?.textContent).not.toContain("Save failed");
+    expect(chip?.querySelector('[data-action="retry-save"]')).not.toBeNull();
+    cleanup();
+  });
+
   it("runs an Operator turn from the conversation and reports the result card", async () => {
     const generated = {
       mutations: [{ selector: "h1", action: "setText" as const, text: "Generated" }],
@@ -326,6 +376,45 @@ describe("editor view v2", () => {
     cleanup();
   });
 
+  it("reports an Operator result as saved with failed publication", async () => {
+    const generated = {
+      mutations: [{ selector: "h1", action: "setText" as const, text: "Committed result" }],
+      customCss: "",
+      customJs: "",
+    };
+    vi.spyOn(operator, "runEditorOperatorTurn").mockResolvedValueOnce({
+      artifacts: generated,
+      explanation: "Updated the heading.",
+      artifactCount: 1,
+      mergeStrategy: "append",
+    });
+    const controller = makeController();
+    controller.applyCommandArtifacts.mockImplementationOnce((artifacts) => {
+      controller.emit(state({ artifacts, saveState: "idle", saveMessage: "Unsaved changes" }));
+      return { ok: true };
+    });
+    controller.saveNow.mockImplementationOnce(async () => {
+      controller.emit(state({
+        artifacts: generated,
+        saveState: "publication_failed",
+        saveMessage: "Saved, but storefront publication failed.",
+      }));
+    });
+    const { shadow, cleanup } = mount(controller);
+
+    const prompt = shadow.querySelector<HTMLTextAreaElement>('[data-field="operator-prompt"]')!;
+    prompt.value = "Update the heading";
+    prompt.dispatchEvent(new Event("input", { bubbles: true }));
+    prompt.closest("form")?.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+
+    await vi.waitFor(() =>
+      expect(shadow.textContent).toContain("Change saved, but publication failed"),
+    );
+    expect(shadow.textContent).toContain("The change is saved in Apex");
+    expect(shadow.textContent).not.toContain("Change applied, but not saved");
+    cleanup();
+  });
+
   it("disables run-level undo after a later manual edit changes the artifact", async () => {
     const generated = {
       mutations: [{ selector: "h1", action: "setText" as const, text: "Generated" }],
@@ -505,6 +594,25 @@ describe("editor view v2", () => {
     cleanup();
   });
 
+  it("keeps the editor open when Save and close cannot publish", async () => {
+    const controller = makeController();
+    controller.saveNow.mockImplementationOnce(async () => {
+      controller.emit(state({
+        saveState: "publication_failed",
+        saveMessage: "Saved, but storefront publication failed.",
+      }));
+    });
+    const { shadow, cleanup } = mount(controller);
+
+    shadow.querySelector<HTMLButtonElement>('[data-action="done"]')?.click();
+    shadow.querySelector<HTMLButtonElement>('[data-action="modal-save-close"]')?.click();
+
+    await vi.waitFor(() => expect(controller.saveNow).toHaveBeenCalled());
+    expect(controller.exit).not.toHaveBeenCalled();
+    expect(shadow.textContent).toContain("Done editing?");
+    cleanup();
+  });
+
   it("extends the session and refreshes the displayed time", async () => {
     const controller = makeController();
     const extended = new Date(Date.now() + 4 * 60 * 1000).toISOString();

package/src/editor/view.ts

@@ -198,7 +198,7 @@ type ThreadUserMessage = {
 type ThreadOperatorMessage = {
   id: number;
   role: "op";
-  phase: "working" | "done" | "failed" | "save-failed";
+  phase: "working" | "done" | "failed" | "save-failed" | "publication-failed";
   step: number;
   steps: string[];
   prompt: string;
@@ -224,7 +224,16 @@ type ChangeEntry = {
   risky: boolean;
 };
 
-type SaveChipStatus = "unsaved" | "saving" | "saved" | "failed" | "conflict" | "loading";
+type SaveChipStatus =
+  | "unsaved"
+  | "saving"
+  | "saved"
+  | "pending"
+  | "warning"
+  | "publication-failed"
+  | "failed"
+  | "conflict"
+  | "loading";
 
 const OPERATOR_SUGGESTIONS = [
   "Make the announcement bar mention free returns",
@@ -269,6 +278,9 @@ function elementNameFromSelector(selector: string): string {
 function saveChipStatus(state: EditorState): SaveChipStatus {
   if (state.saveState === "saving") return "saving";
   if (state.saveState === "saved") return "saved";
+  if (state.saveState === "pending") return "pending";
+  if (state.saveState === "warning") return "warning";
+  if (state.saveState === "publication_failed") return "publication-failed";
   if (state.saveState === "conflict") return "conflict";
   if (state.saveState === "error") return "failed";
   if (!state.variation) return "loading";
@@ -281,15 +293,19 @@ function saveChipHtml(state: EditorState): string {
     status === "unsaved" ? "Unsaved changes"
     : status === "saving" ? "Saving…"
     : status === "saved" ? "Saved"
+    : status === "pending" ? "Saved — publication pending"
+    : status === "warning" ? "Saved — publication warning"
+    : status === "publication-failed" ? "Saved — publication failed"
     : status === "failed" ? "Save failed"
     : status === "conflict" ? "Conflict"
     : "Loading draft…";
   const iconHtml =
     status === "saving" || status === "loading" ? icon("refresh", 12, 'class="spin"')
     : status === "saved" ? icon("check", 12)
+    : status === "pending" || status === "warning" ? icon("alert", 12)
     : status === "unsaved" ? icon("dot", 12)
     : icon("alert", 12);
-  const retry = status === "failed"
+  const retry = status === "failed" || status === "publication-failed"
     ? `<button type="button" class="retry" data-action="retry-save">Retry</button>`
     : "";
   const chipClass = status === "loading" ? "saving" : status;
@@ -602,6 +618,13 @@ export function mountEditorView(
           <div class="row"><button type="button" class="btn sm soft" data-action="retry-save" data-msg="${message.id}">${icon("refresh", 12)}Retry save</button><button type="button" class="btn sm bare" data-action="op-all-changes">${icon("history", 12)}Review changes</button></div>
         </div>`;
       }
+      if (message.phase === "publication-failed") {
+        return `<div class="op-card failed ee-in" role="alert">
+          <div class="head">${icon("alert", 13)} Change saved, but publication failed</div>
+          <p>${esc(message.error ?? "Storefront publication failed.")} The change is saved in Apex. Keep the editor open and retry publication.</p>
+          <div class="row"><button type="button" class="btn sm soft" data-action="retry-save" data-msg="${message.id}">${icon("refresh", 12)}Retry publication</button><button type="button" class="btn sm bare" data-action="op-all-changes">${icon("history", 12)}Review changes</button></div>
+        </div>`;
+      }
       const count = message.results.length;
       const canUndo = canUndoRun(message);
       return `<div class="op-card done ee-in">
@@ -1017,8 +1040,15 @@ export function mountEditorView(
       opMessage.abort = null;
       await controller.saveNow();
       const saveState = controller.getState().saveState;
-      if (saveState === "error" || saveState === "conflict") {
-        opMessage.phase = "save-failed";
+      if (
+        saveState === "error" ||
+        saveState === "conflict" ||
+        saveState === "publication_failed"
+      ) {
+        opMessage.phase =
+          saveState === "publication_failed"
+            ? "publication-failed"
+            : "save-failed";
         opMessage.abort = null;
         opMessage.results = describeRunChanges(preArtifacts, controller.getState().artifacts);
         opMessage.error = controller.getState().saveMessage;
@@ -1091,7 +1121,13 @@ export function mountEditorView(
     );
     await controller.saveNow();
     const saveState = controller.getState().saveState;
-    if (message?.phase === "save-failed" && saveState !== "error" && saveState !== "conflict") {
+    if (
+      (message?.phase === "save-failed" ||
+        message?.phase === "publication-failed") &&
+      saveState !== "error" &&
+      saveState !== "conflict" &&
+      saveState !== "publication_failed"
+    ) {
       message.phase = "done";
       message.error = null;
       message.postArtifacts = stillMatchesRun
@@ -1218,7 +1254,13 @@ export function mountEditorView(
       case "modal-save-close":
         void controller.saveNow().then(() => {
           const saveState = controller.getState().saveState;
-          if (saveState !== "error" && saveState !== "conflict") return controller.exit();
+          if (
+            saveState !== "error" &&
+            saveState !== "conflict" &&
+            saveState !== "publication_failed"
+          ) {
+            return controller.exit();
+          }
           render();
         }).catch(() => render());
         break;

package/src/endpoint.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { normalizeEndpoint } from "./endpoint";
+
+describe("normalizeEndpoint", () => {
+  it("resolves every configured endpoint form to the same base", () => {
+    expect(normalizeEndpoint("https://events.example.com")).toBe("https://events.example.com");
+    expect(normalizeEndpoint("https://events.example.com/")).toBe("https://events.example.com");
+    expect(normalizeEndpoint("https://events.example.com/events")).toBe("https://events.example.com");
+    expect(normalizeEndpoint("https://events.example.com/v1/events")).toBe("https://events.example.com");
+  });
+
+  it("keeps the edge-routed prefix so /_drip siblings still resolve", () => {
+    expect(normalizeEndpoint("https://shop.example.com/_drip/events")).toBe("https://shop.example.com/_drip");
+  });
+});

package/src/endpoint.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize an SDK endpoint: strip trailing slashes and a trailing events path
+ * so configured bare, /events, and /v1/events endpoints resolve to the base.
+ * Single chokepoint — every SDK helper that derives a sibling route from
+ * config.endpoint must go through this (events, handover, order-identity,
+ * replay, shopify cart authorization).
+ */
+export function normalizeEndpoint(endpoint: string): string {
+  return endpoint.replace(/\/+$/, "").replace(/\/(?:v1\/)?events$/, "");
+}

package/src/exclusion-groups.ts

@@ -2,17 +2,15 @@ import type { Assignment, ExclusionGroupConfig } from "./types";
 import { hashToFloat } from "./hash";
 import { chooseVariation } from "./bucket";
 import { deleteCookie, readCookie, writeCookie } from "./guards";
+import { decodeCompactStore } from "./compact-store";
+import { decodePersistedGroupSelections, type PersistedGroupSelection } from "./persistence-decoders";
+export { decodePersistedGroupSelections, type PersistedGroupSelection } from "./persistence-decoders";
 
 const STORAGE_KEY = "drip_xgroups_v1"; // gitleaks:allow — public storage key name, not a credential
 const COOKIE_NAME = "drip_xgroups_v1";
 const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
 
 /** A remembered group decision: which member won and at what group epoch. */
-export type PersistedGroupSelection = {
-  experimentId: string;
-  epoch: number;
-};
-
 /** Pluggable persistence so the runtime uses browser storage and tests use memory. */
 export interface GroupStickyStore {
   read(groupId: string): PersistedGroupSelection | null;
@@ -26,16 +24,8 @@ function normalizeEpoch(epoch: number | null | undefined): number {
   return Number.isFinite(epoch) ? Math.max(1, Math.floor(epoch as number)) : 1;
 }
 
-function parseStore(raw: string | null): CompactStore {
-  if (!raw) return {};
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as CompactStore)
-      : {};
-  } catch {
-    return {};
-  }
+export function decodeCompactGroupStore(raw: string | null): CompactStore {
+  return decodeCompactStore(raw, 2) as CompactStore;
 }
 
 function readLocalStorage(): string | null {
@@ -48,8 +38,8 @@ function readLocalStorage(): string | null {
 
 function readCompactStore(): CompactStore {
   return {
-    ...parseStore(readLocalStorage()),
-    ...parseStore(readCookie(COOKIE_NAME)),
+    ...decodeCompactGroupStore(readLocalStorage()),
+    ...decodeCompactGroupStore(readCookie(COOKIE_NAME)),
   };
 }
 
@@ -265,6 +255,6 @@ export function resolveExclusionGroups(
 export const __exclusionGroupInternals = {
   STORAGE_KEY,
   COOKIE_NAME,
-  parseStore,
+  parseStore: decodeCompactGroupStore,
   normalizeEpoch,
 };

package/src/flags.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   evaluateFlag,
   evaluateFlagAssignment,
@@ -7,6 +7,15 @@ import {
 } from "./flags";
 import type { Experiment } from "./types";
 
+// Hermeticity: weekday tests pin the most recent UTC Monday at 12:00 instead
+// of a literal calendar date.
+const RECENT_MONDAY_NOON = (() => {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() - ((d.getUTCDay() + 6) % 7));
+  d.setUTCHours(12, 0, 0, 0);
+  return d;
+})();
+
 describe("defineFlagExperiment", () => {
   it("creates exactly 2 variations", () => {
     const flag = defineFlagExperiment({
@@ -320,3 +329,81 @@ describe("evaluateFlagValue", () => {
     ).toBe("fallback");
   });
 });
+
+describe("weekday flag delivery", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function scheduledFlag() {
+    return {
+      ...defineFlagExperiment({
+        slug: "weekday-flag",
+        name: "Weekday Flag",
+        rolloutPercent: 0,
+        onValue: "enabled-value",
+      }),
+      weekdaySchedule: {
+        excludedDays: ["monday"],
+        timezone: "UTC",
+      },
+    } as Experiment;
+  }
+
+  it("disables all public flag evaluators on an excluded weekday", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(RECENT_MONDAY_NOON));
+    const flag = {
+      ...scheduledFlag(),
+      variations: scheduledFlag().variations.map((variation) => ({
+        ...variation,
+        weight: variation.id === "enabled" ? 1 : 0,
+      })),
+    };
+    const context = { userId: "user-abc" };
+
+    expect(evaluateFlag("weekday-flag", [flag], context)).toBe(false);
+    expect(evaluateFlagAssignment("weekday-flag", [flag], context)).toBeNull();
+    expect(
+      evaluateFlagValue("weekday-flag", [flag], context, "fallback"),
+    ).toBe("fallback");
+  });
+
+  it("keeps a forced variation enabled on an excluded weekday", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(RECENT_MONDAY_NOON));
+    const flag = scheduledFlag();
+    const context = {
+      userId: "user-abc",
+      forceMap: { "weekday-flag": "enabled" },
+    };
+
+    expect(evaluateFlag("weekday-flag", [flag], context)).toBe(true);
+    expect(
+      evaluateFlagAssignment("weekday-flag", [flag], context)?.variationId,
+    ).toBe("enabled");
+    expect(
+      evaluateFlagValue("weekday-flag", [flag], context, "fallback"),
+    ).toBe("enabled-value");
+  });
+
+  it("keeps flag evaluation unchanged when no weekday schedule exists", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(RECENT_MONDAY_NOON));
+    const flag = defineFlagExperiment({
+      slug: "weekday-flag",
+      name: "Weekday Flag",
+      rolloutPercent: 100,
+      onValue: "enabled-value",
+    });
+    const context = { userId: "user-abc" };
+
+    expect(evaluateFlag("weekday-flag", [flag], context)).toBe(true);
+    expect(
+      evaluateFlagAssignment("weekday-flag", [flag], context)?.variationId,
+    ).toBe("enabled");
+    expect(
+      evaluateFlagValue("weekday-flag", [flag], context, "fallback"),
+    ).toBe("enabled-value");
+  });
+});

package/src/flags.ts

@@ -22,6 +22,7 @@ import { defineExperiment } from "./define";
 import type { Experiment, Assignment } from "./types";
 import { getUserId, hashToFloat, variationHashToFloat } from "./hash";
 import { buildTargetingAttributes, matchesTargeting } from "./targeting";
+import { weekdayScheduleBlocksDelivery } from "./weekday-schedule";
 
 // ---------------------------------------------------------------------------
 // evaluateFlag — check if a flag is ON for a given user
@@ -31,6 +32,8 @@ export interface FlagContext {
   url?: string;
   attributes?: Record<string, unknown>;
   userId?: string;
+  /** QA variation overrides use the same weekday bypass as assignment delivery. */
+  forceMap?: Record<string, string>;
 }
 
 /**
@@ -46,32 +49,8 @@ export function evaluateFlag(
   experiments: Experiment[],
   context?: FlagContext,
 ): boolean {
-  const experiment = experiments.find((e) => e.id === flagId);
-  if (!experiment) return false;
-
-  const url = context?.url ?? (typeof location !== "undefined" ? location.href : "");
-  const attributes = buildTargetingAttributes(context?.attributes ?? {}, url);
-
-  if (!matchesTargeting(experiment.targeting, { url, attributes })) {
-    return false;
-  }
-
-  const userId = getUserId(context?.userId);
-  const hashValue = hashToFloat(experiment.id, userId);
-
-  if (!inTrafficAllocation(hashValue, experiment.trafficAllocation ?? 1)) {
-    return false;
-  }
-
-  const allocation = experiment.trafficAllocation ?? 1;
-  const variationHashValue =
-    allocation >= 1 ? hashValue : variationHashToFloat(experiment.id, userId);
-  const weights = experiment.variations.map((v) => v.weight);
-  const index = chooseVariation(variationHashValue, weights);
-  if (index < 0 || index >= experiment.variations.length) return false;
-
-  const variation = experiment.variations[index];
-  return !variation.isControl;
+  const assignment = evaluateFlagAssignment(flagId, experiments, context);
+  return assignment !== null && !assignment.isControl;
 }
 
 /**
@@ -85,6 +64,21 @@ export function evaluateFlagAssignment(
   const experiment = experiments.find((e) => e.id === flagId);
   if (!experiment) return null;
 
+  const forcedVariationId = context?.forceMap?.[experiment.id];
+  const forcedIndex = forcedVariationId
+    ? experiment.variations.findIndex(
+        (variation) => variation.id === forcedVariationId,
+      )
+    : -1;
+  const forcedVariation =
+    forcedIndex >= 0 ? experiment.variations[forcedIndex] : null;
+  if (
+    !forcedVariation &&
+    weekdayScheduleBlocksDelivery(experiment.weekdaySchedule, new Date())
+  ) {
+    return null;
+  }
+
   const url = context?.url ?? (typeof location !== "undefined" ? location.href : "");
   const attributes = buildTargetingAttributes(context?.attributes ?? {}, url);
 
@@ -95,7 +89,10 @@ export function evaluateFlagAssignment(
   const userId = getUserId(context?.userId);
   const hashValue = hashToFloat(experiment.id, userId);
 
-  if (!inTrafficAllocation(hashValue, experiment.trafficAllocation ?? 1)) {
+  if (
+    !forcedVariation &&
+    !inTrafficAllocation(hashValue, experiment.trafficAllocation ?? 1)
+  ) {
     return null;
   }
 
@@ -103,15 +100,18 @@ export function evaluateFlagAssignment(
   const variationHashValue =
     allocation >= 1 ? hashValue : variationHashToFloat(experiment.id, userId);
   const weights = experiment.variations.map((v) => v.weight);
-  const index = chooseVariation(variationHashValue, weights);
+  const index = forcedVariation
+    ? forcedIndex
+    : chooseVariation(variationHashValue, weights);
   if (index < 0 || index >= experiment.variations.length) return null;
 
-  const variation = experiment.variations[index];
+  const variation = forcedVariation ?? experiment.variations[index];
 
   return {
     experimentId: experiment.id,
     experimentName: undefined,
     variationId: variation.id,
+    pageActive: true,
     index,
     mutations: variation.mutations ?? [],
     value: variation.value,