@apex-inc/sdk 0.25.0 → 0.28.0

package/dist/management.js

@@ -45,7 +45,7 @@ function communicationPipeline(commType) {
 function createManagementClient(cfg) {
     const root = baseUrl(cfg);
     const headers = keyHeaders(cfg);
-    return {
+    const client = {
         async listExperiments() {
             const res = await fetch(`${root}/api/experiments?unified=true`, { headers });
             if (!res.ok) {
@@ -228,6 +228,29 @@ function createManagementClient(cfg) {
          * Will this edit hit a live test? Advisory only — does not stamp or mail.
          * Call before editing a page or committing.
          */
+        /**
+         * Who else is live on this page? Overlap lists plus same-page neighbors.
+         * Advisory only. Neighbors are different named parts on the same URL.
+         */
+        async checkConflicts(opts) {
+            const res = await fetch(`${root}/api/experiments/check-conflicts`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    experiment_id: opts.experimentId,
+                    surface: opts.surface,
+                    target_url: opts.targetUrl,
+                    target_anchor: opts.targetAnchor,
+                    target_component: opts.targetComponent,
+                    data_source_id: opts.dataSourceId,
+                    primary_metric_event: opts.primaryMetricEvent,
+                }),
+            });
+            if (!res.ok) {
+                throw new Error(`Apex checkConflicts failed (${res.status}): ${await res.text().catch(() => "")}`);
+            }
+            return res.json();
+        },
         async checkLiveTests(opts) {
             const res = await fetch(`${root}/api/experiments/check-live-tests`, {
                 method: "POST",
@@ -248,7 +271,7 @@ function createManagementClient(cfg) {
         },
         /**
          * The shop says the change was not the thing under test. Restores a
-         * fair comparison. Cannot mark a test touched — only Apex's matcher does.
+         * fair comparison. Silence also leaves the numbers fair.
          */
         async markTreatmentOrthogonal(id) {
             const res = await fetch(`${root}/api/experiments/${encodeURIComponent(id)}`, {
@@ -261,6 +284,21 @@ function createManagementClient(cfg) {
             }
             return res.json();
         },
+        /**
+         * The shop says that change was the test. Marks the run Contaminated.
+         * Apex will not call a winner or learn from it. Offer a new run.
+         */
+        async markTreatmentContaminated(id) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(id)}`, {
+                method: "PATCH",
+                headers,
+                body: JSON.stringify({ treatment_touch: { status: "touched" } }),
+            });
+            if (!res.ok) {
+                throw new Error(`Apex markTreatmentContaminated failed (${res.status}): ${await res.text().catch(() => "")}`);
+            }
+            return res.json();
+        },
         async activateExperiment(id) {
             const res = await fetch(`${root}/api/experiments`, {
                 method: "PATCH",
@@ -1525,5 +1563,286 @@ function createManagementClient(cfg) {
             },
         },
     };
+    // ─── Experiments (Mobile Measurement P1 regroup, 2026-09-14) ─────────
+    //
+    // The experiment methods used to sit flat on the client next to
+    // `adoption.*`, `communications.*`, `conversions.*`. They now live under
+    // `experiments.*` like every other surface. The flat names stay as
+    // deprecated aliases so nothing that already calls
+    // `apexClient.listExperiments()` breaks on a minor bump.
+    const experiments = {
+        /** List the workspace's experiments (unified: web, code, comm, journey). */
+        list: client.listExperiments,
+        /** One experiment by id. */
+        get: client.getExperiment,
+        /** Per-arm results for an experiment. */
+        getResults: client.getExperimentResults,
+        /** Start serving a draft. */
+        activate: client.activateExperiment,
+        /** Make the winner permanent. */
+        promote: client.promoteExperiment,
+        /** Server-side arm for a visitor. */
+        assignVariant: client.assignVariant,
+        /** Would a new treatment collide with a running test? */
+        checkConflicts: client.checkConflicts,
+        /** Is anything live on these files / comms / journeys / milestones? */
+        checkLiveTests: client.checkLiveTests,
+        markTreatmentOrthogonal: client.markTreatmentOrthogonal,
+        markTreatmentContaminated: client.markTreatmentContaminated,
+        /**
+         * Ad holdout (Mobile Measurement P3a): hold a share of the workspace's
+         * known people back from the ads on one network's ad sets and measure
+         * the installs the ads actually cause. Creates a DRAFT; call
+         * `activate` to draw the list. Nothing counts until Apex confirms the
+         * do-not-show list is on every ad set (`verifyAdExclusion`).
+         *
+         * Wraps `POST /api/experiments` with surface `paid_channel`, the same
+         * route the dashboard wizard and the MCP `create_experiment` use.
+         * Admin-only, and the workspace must have Ad holdouts switched on.
+         */
+        async createAdHoldout(params) {
+            const { name, hypothesis, runtimeDays, beliefId, predictionMagnitude, ...paidChannel } = params;
+            const attachMode = paidChannel.attachMode ?? (paidChannel.network === "meta" ? "apex" : "manual");
+            const days = runtimeDays ?? 28;
+            const res = await fetch(`${root}/api/experiments`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    surface: "paid_channel",
+                    name,
+                    hypothesis: hypothesis ??
+                        `The ads on ${paidChannel.adSetIds.length === 1 ? "this ad set" : `these ${paidChannel.adSetIds.length} ad sets`} cause installs that would not have happened without them.`,
+                    createdFrom: "sdk",
+                    status: "draft",
+                    paidChannel: {
+                        network: paidChannel.network,
+                        adAccountId: paidChannel.adAccountId,
+                        adSetIds: paidChannel.adSetIds,
+                        holdoutPercent: paidChannel.holdoutPercent,
+                        attachMode,
+                        washoutDays: paidChannel.washoutDays ?? 3,
+                        ...(paidChannel.populationSegmentId ? { populationSegmentId: paidChannel.populationSegmentId } : {}),
+                        ...(paidChannel.campaignNames?.length ? { campaignNames: paidChannel.campaignNames } : {}),
+                    },
+                    decisionWindow: { unit: "days", value: days, startFrom: "assignment" },
+                    ...(beliefId ? { beliefId } : {}),
+                    ...(predictionMagnitude
+                        ? { prediction: { direction: "increase", magnitude: predictionMagnitude, provenance: "merchant" } }
+                        : {}),
+                }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex experiments.createAdHoldout failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /**
+         * Ask Apex to check right now whether the do-not-show list is on every
+         * ad set the holdout covers, and record the answer. Rate-limited: a
+         * recent check returns the last reading (`skipped: true`) instead of
+         * re-reading the network. Wraps
+         * `GET /api/experiments/{id}/ad-exclusion/verify`.
+         */
+        async verifyAdExclusion(experimentId) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(experimentId)}/ad-exclusion/verify`, { headers });
+            const json = (await res.json().catch(() => null));
+            if (res.status === 429 && json?.data) {
+                return { ...json.data, skipped: true, retryAfterSeconds: json.retryAfterSeconds };
+            }
+            if (!res.ok || !json?.data) {
+                throw new Error(`Apex experiments.verifyAdExclusion failed (${res.status}): ${json?.error ?? ""}`);
+            }
+            return json.data;
+        },
+        /**
+         * What Apex would change on the holdout's ad sets, without changing it:
+         * each ad set's exclusion list before and after, the one id added, and
+         * whether the workspace's standing allowance for Apex to edit ad-set
+         * targeting is on file. Any member may call it; it writes nothing.
+         * Meta only. Wraps `GET /api/experiments/{id}/ad-exclusion/attach`.
+         */
+        async previewAdExclusion(experimentId) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(experimentId)}/ad-exclusion/attach`, { headers });
+            const json = (await res.json().catch(() => null));
+            if (!res.ok || !json?.data) {
+                throw new Error(`Apex experiments.previewAdExclusion failed (${res.status}): ${json?.error ?? ""}`);
+            }
+            return json.data;
+        },
+        /**
+         * Apex puts the held-back list on the holdout's ad sets (Mobile
+         * Measurement P3b, Meta only). Adds exactly one exclusion per ad set;
+         * every other targeting key is left as read, and Apex reads back to
+         * confirm. Admin-only. The workspace must have allowed Apex to edit
+         * ad-set targeting once: pass `acknowledge: true` on the first call,
+         * after showing the preview; later calls ride on the allowance. Without
+         * it the call fails with 409 `needs_targeting_ack` and nothing is edited.
+         * Not billed. Wraps `POST /api/experiments/{id}/ad-exclusion/attach`.
+         */
+        async attachAdExclusion(experimentId, opts = {}) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(experimentId)}/ad-exclusion/attach`, { method: "POST", headers, body: JSON.stringify(opts.acknowledge ? { acknowledge: true } : {}) });
+            const json = (await res.json().catch(() => null));
+            if (!res.ok || !json?.data) {
+                throw new Error(`Apex experiments.attachAdExclusion failed (${res.status}${json?.code ? ` ${json.code}` : ""}): ${json?.error ?? ""}`);
+            }
+            return json.data;
+        },
+        /**
+         * Take Apex's exclusion back off the ad sets and delete the held-back
+         * list. Only removes what Apex added; a list the shop attached by hand
+         * is refused with 409 `not_apex_attached`. Admin-only. Ending, pausing
+         * or archiving the holdout does this on its own; call it to undo an
+         * attach early. Wraps `POST /api/experiments/{id}/ad-exclusion/detach`.
+         */
+        async detachAdExclusion(experimentId) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(experimentId)}/ad-exclusion/detach`, { method: "POST", headers });
+            const json = (await res.json().catch(() => null));
+            if (!res.ok || !json?.data) {
+                throw new Error(`Apex experiments.detachAdExclusion failed (${res.status}${json?.code ? ` ${json.code}` : ""}): ${json?.error ?? ""}`);
+            }
+            return json.data;
+        },
+    };
+    // ─── Apex Links ───────────────────────────────────────────────────────
+    //
+    // Trackable links (short URL, store routing, deferred deep link, UTMs).
+    // Wraps `/api/mobile/links`, the same route the dashboard and MCP use.
+    const links = {
+        /** List the workspace's Apex Links. */
+        async list(opts) {
+            const qs = new URLSearchParams();
+            if (opts?.ownerType)
+                qs.set("ownerType", opts.ownerType);
+            if (opts?.ownerId)
+                qs.set("ownerId", opts.ownerId);
+            if (opts?.enabled !== undefined)
+                qs.set("enabled", String(opts.enabled));
+            if (opts?.archived !== undefined)
+                qs.set("archived", String(opts.archived));
+            if (opts?.limit !== undefined)
+                qs.set("limit", String(opts.limit));
+            const q = qs.toString();
+            const res = await fetch(`${root}/api/mobile/links${q ? `?${q}` : ""}`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex links.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+            const json = (await res.json());
+            return json.links ?? [];
+        },
+        /**
+         * Create an Apex Link. `slug` becomes the short path; `destinationUrl`
+         * is where the web falls back. Store fallbacks are derived from the
+         * workspace's app config unless given.
+         */
+        async create(params) {
+            const res = await fetch(`${root}/api/mobile/links`, {
+                method: "POST", headers, body: JSON.stringify(params),
+            });
+            if (!res.ok)
+                throw new Error(`Apex links.create failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+    };
+    // ─── Mobile Measurement ──────────────────────────────────────────────
+    //
+    // Install attribution, SKAN values and Ad holdouts land here as the
+    // Mobile Measurement plan ships (P2–P3a).
+    const mobile = {
+        /**
+         * SKAdNetwork conversion values: what Apple's 0–63 numbers mean for
+         * this app. Wraps `/api/mobile/skan/schema`, the same route the
+         * dashboard's "Say what Apple's numbers mean" step saves through.
+         * The Capacitor plugin reads the anonymous `/resolve` twin of this
+         * route on the device.
+         */
+        skan: {
+            /**
+             * Read the schema. `mobileAppId` picks an app; omit it for the
+             * workspace's first app. `schema` is null until the shop names its
+             * values.
+             */
+            async getSchema(opts) {
+                const q = opts?.mobileAppId ? `?mobileAppId=${encodeURIComponent(opts.mobileAppId)}` : "";
+                const res = await fetch(`${root}/api/mobile/skan/schema${q}`, { headers });
+                if (!res.ok)
+                    throw new Error(`Apex mobile.skan.getSchema failed (${res.status}): ${await res.text().catch(() => "")}`);
+                const json = (await res.json());
+                return json.data;
+            },
+            /**
+             * Replace the schema. Workspace admin (or an `apex_sk_` key). Range,
+             * enum and one-value-per-event-per-window checks run server-side;
+             * a 400 carries `problems` with a path per fault. `updatedAt` is
+             * stamped by Apex, so you may omit it.
+             */
+            async setSchema(params) {
+                const res = await fetch(`${root}/api/mobile/skan/schema`, {
+                    method: "PUT", headers, body: JSON.stringify(params),
+                });
+                if (!res.ok)
+                    throw new Error(`Apex mobile.skan.setSchema failed (${res.status}): ${await res.text().catch(() => "")}`);
+                const json = (await res.json());
+                return json.data;
+            },
+        },
+    };
+    // ─── Beliefs ─────────────────────────────────────────────────────────
+    //
+    // What the shop believes and what its experiments have said about it.
+    // `suggestions` is the "Worth writing down" rail: settled experiments
+    // whose verdict passes the belief gate (decisive, exclusion attached the
+    // whole window, no SRM, no guardrail breach, both arms over the events
+    // floor) and have not been written down yet. Statistical only.
+    const beliefs = {
+        /** The workspace's beliefs. */
+        async list() {
+            const res = await fetch(`${root}/api/beliefs`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex beliefs.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+            const json = (await res.json());
+            return Array.isArray(json) ? json : json.data;
+        },
+        suggestions: {
+            /**
+             * Settled experiments worth writing down as a belief. Pass
+             * `experimentId` for one experiment; then `blocker` says in one word
+             * why it is not offered (`not_decisive`, `srm`, `guardrail_breach`,
+             * `exclusion_not_attached`, `results_frozen`, `events_floor`,
+             * `already_written`).
+             */
+            async list(opts) {
+                const qs = new URLSearchParams();
+                if (opts?.experimentId)
+                    qs.set("experiment_id", opts.experimentId);
+                if (opts?.max !== undefined)
+                    qs.set("max", String(opts.max));
+                const q = qs.toString();
+                const res = await fetch(`${root}/api/experiments/belief-suggestions${q ? `?${q}` : ""}`, { headers });
+                if (!res.ok)
+                    throw new Error(`Apex beliefs.suggestions.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+                const json = (await res.json());
+                return json.data;
+            },
+            /**
+             * Write one down. Creates a Belief with the experiment as its
+             * evidence and `generatedFromExperimentId` set; the evidence state
+             * starts at `one_study`. `statement` is your edit of the sentence;
+             * the numbers stay Apex's. Workspace admin (or an `apex_sk_` key).
+             * The gate re-runs here: a 422 carries `blocker`; a 409 means it was
+             * already written and hands back that belief.
+             */
+            async accept(params) {
+                const res = await fetch(`${root}/api/experiments/belief-suggestions/accept`, {
+                    method: "POST", headers, body: JSON.stringify(params),
+                });
+                const json = (await res.json().catch(() => null));
+                if (res.status === 409 && json?.data)
+                    return json.data;
+                if (!res.ok || !json?.data) {
+                    throw new Error(`Apex beliefs.suggestions.accept failed (${res.status}${json?.blocker ? ` ${json.blocker}` : ""}): ${json?.error ?? ""}`);
+                }
+                return json.data;
+            },
+        },
+    };
+    return { ...client, experiments, links, mobile, beliefs };
 }
 //# sourceMappingURL=management.js.map