@startsimpli/funnels 0.4.14 → 0.4.16

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@startsimpli/funnels",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "Brutally generic filtering pipeline package for any Simpli product",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./page": "./src/page/index.ts",
     "./core": "./src/core/index.ts",
     "./components": "./src/components/index.ts",
     "./hooks": "./src/hooks/index.ts",
@@ -48,7 +49,8 @@
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "zustand": "^4.0.0 || ^5.0.0"
+    "zustand": "^4.0.0 || ^5.0.0",
+    "@startsimpli/ui": "^0.4.125"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.1.2",
@@ -75,7 +77,8 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "zustand": "^5.0.12"
+    "zustand": "^5.0.12",
+    "@startsimpli/ui": "0.4.125"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -83,6 +86,11 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@xyflow/react": "^12.10.2"
   },
+  "peerDependenciesMeta": {
+    "@startsimpli/ui": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/src/api/client.paths.test.ts

@@ -60,21 +60,34 @@ describe('FunnelApiClient path injection', () => {
     await client.getFunnel('f1');
     expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/');
 
+    // Triggering is a POST to the run COLLECTION on this surface: the control
+    // plane mounts ONE `funnel_runs` action where GET lists and POST triggers.
     await client.runFunnel('f1');
-    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/run/');
+    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
 
     await client.getFunnelRuns('f1');
     expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
   });
 
-  it('addresses a nested run through its funnel on the control plane', async () => {
+  it('addresses a run on the control plane’s sibling funnel-runs collection', async () => {
+    // Corrected in bd startsim-em5mn. The action is
+    // `funnel-runs/(?P<run_id>[^/.]+)/results` — a SIBLING of `funnels/`,
+    // because `runs/` on FoundryViewSet is already the foundry's own build
+    // history. The previous `nestRuns: true` built `funnels/f1/runs/r1/…`,
+    // which resolves to no route at all (verified against prod 2026-09-18).
     const client = new FunnelApiClient(adapter, '', foundryTenantFunnelPaths('acme'));
-    await client.getFunnelRun('r1', 'f1');
-    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/r1/');
     await client.getFunnelResults('r1', { funnelId: 'f1' });
-    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/r1/results/');
-    await client.cancelFunnelRun('r1', 'f1');
-    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/r1/cancel/');
+    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnel-runs/r1/results/');
+    // ...and the funnel id is not needed to address it.
+    await client.getFunnelResults('r1');
+    expect(adapter.lastUrl).toBe('/api/v1/foundry/tenants/acme/funnel-runs/r1/results/');
+  });
+
+  it('carries the stage-reached filter through as a query param', async () => {
+    const client = new FunnelApiClient(adapter, '', foundryTenantFunnelPaths('acme'));
+    await client.getFunnelResults('r1', { stage: 's1', matched: false, funnelId: 'f1' });
+    // `funnelId` addresses the URL and must not leak into the query string.
+    expect(adapter.calls.at(-1)!.params).toEqual({ stage: 's1', matched: false });
   });
 
   it('talks through a tenant proxy prefix', async () => {

package/src/api/client.ts

@@ -326,6 +326,12 @@ export class FunnelApiClient {
     runId: string,
     filters?: {
       matched?: boolean;
+      /**
+       * WHERE THE ENTITY STOPPED. A stage id is "excluded at that stage";
+       * the literal 'end' is "was never excluded" (bd startsim-9xbz2). Served
+       * by the control-plane results action; the central one ignores it.
+       */
+      stage?: string;
       page?: number;
       pageSize?: number;
       /** Required only on a family that nests runs under their funnel. */

package/src/api/http-adapter.test.ts

@@ -0,0 +1,68 @@
+/**
+ * The bridge from an app's own http client to the funnel adapter
+ * (bd startsim-em5mn).
+ */
+import { describe, it, expect } from 'vitest';
+import { funnelHttpAdapter } from './http-adapter';
+import { FunnelApiClient } from './client';
+import { foundryTenantFunnelPaths } from './paths';
+
+function spy() {
+  const calls: Array<{ method: string; endpoint: string; arg?: unknown }> = [];
+  const http = {
+    get: <T,>(endpoint: string, options?: { params?: Record<string, unknown> }) => {
+      calls.push({ method: 'get', endpoint, arg: options });
+      return Promise.resolve({ results: [], count: 0 } as unknown as T);
+    },
+    post: <T,>(endpoint: string, data?: unknown) => {
+      calls.push({ method: 'post', endpoint, arg: data });
+      return Promise.resolve({} as T);
+    },
+    patch: <T,>(endpoint: string, data?: unknown) => {
+      calls.push({ method: 'patch', endpoint, arg: data });
+      return Promise.resolve({} as T);
+    },
+    delete: <T,>(endpoint: string) => {
+      calls.push({ method: 'delete', endpoint });
+      return Promise.resolve(undefined as T);
+    },
+  };
+  return { http, calls };
+}
+
+describe('funnelHttpAdapter', () => {
+  it('hands query params to the http client under `params`', async () => {
+    const { http, calls } = spy();
+    const client = new FunnelApiClient(funnelHttpAdapter(http), '', foundryTenantFunnelPaths('acme'));
+
+    await client.listFunnels({ page: 2, pageSize: 25, status: 'active' });
+
+    expect(calls[0]).toEqual({
+      method: 'get',
+      endpoint: '/api/v1/foundry/tenants/acme/funnels/',
+      // `pageSize`, NOT `page_size`: StandardPaginatedResponse reads
+      // `pageSize`. Transforming the key here would silently page at 25 forever.
+      arg: { params: { page: 2, pageSize: 25, status: 'active' } },
+    });
+  });
+
+  it('omits the options object entirely when there are no params', async () => {
+    const { http, calls } = spy();
+    const client = new FunnelApiClient(funnelHttpAdapter(http), '', foundryTenantFunnelPaths('acme'));
+
+    await client.getFunnel('f1');
+
+    expect(calls[0].arg).toBeUndefined();
+  });
+
+  it('passes a write body straight through', async () => {
+    const { http, calls } = spy();
+    const client = new FunnelApiClient(funnelHttpAdapter(http), '', foundryTenantFunnelPaths('acme'));
+
+    await client.runFunnel('f1', { triggerType: 'manual' });
+
+    expect(calls[0].method).toBe('post');
+    expect(calls[0].endpoint).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
+    expect(calls[0].arg).toEqual({ triggerType: 'manual' });
+  });
+});

package/src/api/http-adapter.ts

@@ -0,0 +1,48 @@
+/**
+ * Drive FunnelApiClient with an app's OWN http client (bd startsim-em5mn).
+ *
+ * WHY THIS IS HERE AND NOT IN EACH APP. Every surface that mounts the funnels
+ * page already has a configured client — `@startsimpli/api`'s, carrying the
+ * bearer token, the 401 bounce to central auth and the snake↔camel key
+ * transform. `FetchAdapter` has none of that, so an app wiring the page with it
+ * would be signing its own requests. The three-line bridge between the two is
+ * the same three lines in foundry-web, the tenant template and market-web, so
+ * it lives here once (CLAUDE.md rule 9) — the same shape
+ * `createPlanningApi({ http: api.client })` already takes.
+ *
+ * STRUCTURAL, NOT IMPORTED. The parameter is an interface this module declares
+ * rather than `ApiClient` from `@startsimpli/api`, so `@startsimpli/funnels`
+ * gains no dependency on it: raise and market install funnels precisely because
+ * it is light, and any client with these four methods works.
+ *
+ * QUERY PARAMS ARE PASSED THROUGH UNTOUCHED, deliberately. The page sends
+ * `page` and `pageSize` because that is what the server's paginator reads
+ * (`StandardPaginatedResponse.page_size_query_param = 'pageSize'`), and
+ * `entity_type` / `stage` / `matched` because those are the filter names the
+ * funnels endpoints read. Snake-casing them here would break the first pair and
+ * camel-casing them would break the second; the caller already spells each one
+ * the way its endpoint wants it.
+ */
+import type { ApiAdapter } from './adapter';
+
+/**
+ * The slice of an http client this adapter needs. `@startsimpli/api`'s
+ * `ApiClient` satisfies it as-is.
+ */
+export interface FunnelHttpClient {
+  get<T>(endpoint: string, options?: { params?: Record<string, unknown> }): Promise<T>;
+  post<T>(endpoint: string, data?: unknown): Promise<T>;
+  patch<T>(endpoint: string, data?: unknown): Promise<T>;
+  delete<T>(endpoint: string): Promise<T>;
+}
+
+/** Wrap an app's http client as the adapter FunnelApiClient takes. */
+export function funnelHttpAdapter(http: FunnelHttpClient): ApiAdapter {
+  return {
+    get: <T,>(url: string, params?: Record<string, unknown>) =>
+      http.get<T>(url, params ? { params } : undefined),
+    post: <T,>(url: string, data: unknown) => http.post<T>(url, data),
+    patch: <T,>(url: string, data: unknown) => http.patch<T>(url, data),
+    delete: <T,>(url: string) => http.delete<T>(url),
+  };
+}

package/src/api/index.ts

@@ -15,6 +15,11 @@ export { createApiError, isApiError } from './adapter';
 export { FetchAdapter } from './default-adapter';
 export type { FetchAdapterConfig } from './default-adapter';
 
+// Bridge an app's own configured http client (auth, 401 bounce, key transform)
+// into the adapter this client takes — bd startsim-em5mn.
+export { funnelHttpAdapter } from './http-adapter';
+export type { FunnelHttpClient } from './http-adapter';
+
 // Path families — the surfaces the same client can talk to (bd startsim-pxzlf)
 export {
   createFunnelPaths,

package/src/api/paths.test.ts

@@ -105,16 +105,29 @@ describe('foundryTenantFunnelPaths', () => {
     const paths = foundryTenantFunnelPaths('acme');
     expect(paths.list()).toBe('/api/v1/foundry/tenants/acme/funnels/');
     expect(paths.detail('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/');
-    expect(paths.run('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/run/');
     expect(paths.runs('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
-    expect(paths.fields()).toBe('/api/v1/foundry/tenants/acme/funnels/fields/');
   });
 
-  it('nests runs under the funnel, which is how the nested viewset addresses them', () => {
+  it('triggers a run by POSTing to the runs COLLECTION, not to a run/ action', () => {
+    // FoundryViewSet mounts ONE `funnel_runs` action: GET lists, POST triggers.
+    // `funnels/<id>/run/` reaches no route there (verified against prod
+    // 2026-09-18: Django's 404 HTML, not a DRF body). bd startsim-em5mn.
     const paths = foundryTenantFunnelPaths('acme');
-    expect(paths.runDetail('r1', 'f1')).toBe(
-      '/api/v1/foundry/tenants/acme/funnels/f1/runs/r1/'
+    expect(paths.run('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
+    expect(paths.run('f1')).toBe(paths.runs('f1'));
+  });
+
+  it('addresses a run on the sibling funnel-runs collection, not under its funnel', () => {
+    // The action is `funnel-runs/(?P<run_id>[^/.]+)/results` — a sibling of
+    // `funnels/`, because `runs/` on that viewset is already the foundry's own
+    // build history. The old `nestRuns: true` built
+    // `funnels/f1/runs/r1/results/`, which has never resolved.
+    const paths = foundryTenantFunnelPaths('acme');
+    expect(paths.runResults('r1')).toBe(
+      '/api/v1/foundry/tenants/acme/funnel-runs/r1/results/'
     );
+    // ...and it does NOT need the funnel id to do it.
+    expect(paths.runResults('r1', 'f1')).toBe(paths.runResults('r1'));
   });
 
   it('encodes the slug', () => {

package/src/api/paths.ts

@@ -57,9 +57,20 @@ export interface FunnelPathsOptions {
   runsPrefix?: string;
   /**
    * Address a run under its funnel (<prefix>/<funnelId>/runs/<runId>/) instead
-   * of on its own. The control-plane viewset nests them this way.
+   * of on its own.
    */
   nestRuns?: boolean;
+  /**
+   * Trigger a run by POSTing to the run COLLECTION (<prefix>/<id>/runs/)
+   * rather than to a separate <prefix>/<id>/run/ action.
+   *
+   * The control plane is built this way — one `funnel_runs` action where GET
+   * lists and POST triggers — while the central API keeps `run/` and `runs/`
+   * as two endpoints. Verified against prod 2026-09-18: a POST to the control
+   * plane's `funnels/<id>/run/` reaches no route at all (Django 404 HTML,
+   * not a DRF body), whereas `funnels/<id>/runs/` answers.
+   */
+  triggerOnRunsCollection?: boolean;
 }
 
 function trimSlashes(value: string): string {
@@ -86,6 +97,7 @@ export function createFunnelPaths(options: FunnelPathsOptions = {}): FunnelPaths
   const prefix = trimSlashes(options.prefix ?? DEFAULT_FUNNEL_PATH_PREFIX);
   const runsPrefix = trimSlashes(options.runsPrefix ?? DEFAULT_FUNNEL_RUNS_PATH_PREFIX);
   const nestRuns = options.nestRuns ?? false;
+  const triggerOnRunsCollection = options.triggerOnRunsCollection ?? false;
 
   function runBase(runId: string, funnelId?: string): string {
     if (!nestRuns) return `${runsPrefix}/${segment(runId)}`;
@@ -110,7 +122,10 @@ export function createFunnelPaths(options: FunnelPathsOptions = {}): FunnelPaths
     // (config/api_router.py: path("funnels/fields/", FunnelFieldsView…)).
     fields: () => `${prefix}/fields/`,
 
-    run: (funnelId) => `${prefix}/${segment(funnelId)}/run/`,
+    run: (funnelId) =>
+      triggerOnRunsCollection
+        ? `${prefix}/${segment(funnelId)}/runs/`
+        : `${prefix}/${segment(funnelId)}/run/`,
     runs: (funnelId) => `${prefix}/${segment(funnelId)}/runs/`,
     runDetail: (runId, funnelId) => `${runBase(runId, funnelId)}/`,
     runResults: (runId, funnelId) => `${runBase(runId, funnelId)}/results/`,
@@ -122,13 +137,44 @@ export function createFunnelPaths(options: FunnelPathsOptions = {}): FunnelPaths
 export const centralFunnelPaths: FunnelPaths = createFunnelPaths();
 
 /**
- * The control-plane family for one foundry (startsim-9xbz2):
- * /api/v1/foundry/tenants/<slug>/funnels/… with runs nested under their funnel.
+ * The control-plane family for one foundry (startsim-9xbz2).
+ *
+ * CORRECTED against the routes FoundryViewSet actually mounts (bd
+ * startsim-em5mn). Every URL below was exercised against prod on 2026-09-18 as
+ * the foundry QA owner; the ones marked ✗ answered with Django's 404 HTML page,
+ * which is what "this path reaches no route at all" looks like, as opposed to
+ * the DRF `{"error": …}` body a real route returns for a missing row.
+ *
+ *   ✓ funnels/                       GET list, POST create
+ *   ✓ funnels/<id>/                  GET, PATCH, DELETE
+ *   ✓ funnels/<id>/runs/             GET history, POST trigger (202)
+ *   ✓ funnel-runs/<runId>/results/   GET, paged, ?matched= ?stage=
+ *   ✗ funnels/<id>/run/              — trigger is a POST to `runs/`
+ *   ✗ funnels/<fid>/runs/<rid>/…     — results hang off `funnel-runs/`, a
+ *                                      SIBLING of `funnels/`, not under it
+ *   ✗ funnels/<id>/stages/           — stages are written nested in the funnel
+ *   ✗ funnels/<id>/preview/          — no preview action exists here
+ *
+ * The previous definition passed `nestRuns: true`, which built
+ * `funnels/<fid>/runs/<rid>/results/` — a path that has never resolved. It had
+ * no runtime consumer, so nothing was broken by it and nothing is broken by
+ * this correction; it was simply never driven by a page until now.
+ *
+ * `fields()` REMAINS A LIE ON THIS SURFACE and is the one thing this function
+ * cannot fix. `funnels/fields/` matches the `funnels/(?P<funnel_id>[^/.]+)`
+ * action first (DRF orders extra actions by method name, and `funnel_detail`
+ * sorts before any `funnel_fields` would), so it 404s with "funnel not found".
+ * The vocabulary is only served from central `/api/v1/funnels/fields/`, scoped
+ * to the CALLER's company. That is why FunnelsPage takes its fields client as a
+ * separate injection instead of reading `client.paths.fields()` — see
+ * `src/page/FunnelsPage.tsx`. bd startsim-em5mn.1 tracks mounting the route.
  */
 export function foundryTenantFunnelPaths(slug: string): FunnelPaths {
+  const base = `/api/v1/foundry/tenants/${segment(slug)}`;
   return createFunnelPaths({
-    prefix: `/api/v1/foundry/tenants/${segment(slug)}/funnels`,
-    nestRuns: true,
+    prefix: `${base}/funnels`,
+    runsPrefix: `${base}/funnel-runs`,
+    triggerOnRunsCollection: true,
   });
 }