@startsimpli/funnels 0.4.14 → 0.4.15

package/src/page/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @startsimpli/funnels/page — the whole Funnels screen, mounted not rebuilt.
+ *
+ * A SUBPATH AND NOT THE ROOT BARREL, deliberately (the same reasoning
+ * `@startsimpli/ui/foundry` writes down for itself). This module is the one
+ * thing in the package that needs `@startsimpli/ui` — for UnifiedTable, and so
+ * for repo rule #8's server-side paging. raise and market import
+ * `@startsimpli/funnels` for the engine and the rule editor and must not be
+ * made to install a UI library to get them, so the import lives behind
+ *
+ *     import { FunnelsPage } from '@startsimpli/funnels/page'
+ *
+ * and `@startsimpli/ui` is an OPTIONAL peer dependency.
+ *
+ * bd startsim-em5mn.
+ */
+export { FunnelsPage } from './FunnelsPage';
+export type {
+  FunnelsPageProps,
+  FunnelListRow,
+  FunnelResultRow,
+  FunnelListQuery,
+  StageReached,
+} from './types';

package/src/page/types.ts

@@ -0,0 +1,102 @@
+/**
+ * What the FunnelsPage composer is handed, and the row shapes it renders.
+ *
+ * The wire shapes below are DECLARED HERE rather than in `../types` on purpose.
+ * `../types` is the funnel CONTRACT — the shapes paired with
+ * `@startsimpli/api`'s by `contract.test.ts`, changed only in lockstep. What a
+ * LIST endpoint adds on top (`stage_count`, `total_runs`, `last_run_*`) and
+ * what `FunnelResultSerializer` emits per row are presentation payloads: this
+ * page is their only reader, so widening the contract for them would make two
+ * packages agree about something neither of them models.
+ *
+ * bd startsim-em5mn.
+ */
+import type { FunnelApiClient } from '../api/client';
+import type { Funnel, FunnelStatus } from '../types';
+
+/**
+ * A funnel as a LIST answers it: the contract shape plus the rollups
+ * `FunnelSerializer` computes (`stage_count`, `total_runs`, `last_run_at`,
+ * `last_run_id`, `last_run_matched`, `created_by_name`), camelized by the
+ * adapter.
+ */
+export interface FunnelListRow extends Funnel {
+  stageCount?: number;
+  totalRuns?: number;
+  lastRunAt?: string | null;
+  lastRunId?: string | null;
+  lastRunMatched?: number | null;
+  createdByName?: string | null;
+}
+
+/** Where a result stopped, named from what the run RECORDED (breakdown.py). */
+export interface StageReached {
+  id: string;
+  name: string | null;
+  order: number | null;
+}
+
+/**
+ * One row of a run's results, as the control plane serves them.
+ *
+ * `context` is free-form and reaches the browser through an adapter that
+ * camelizes KEYS, so it is rendered as an opaque count rather than as fields:
+ * a key the executor wrote as `reached_stage_id` arrives as `reachedStageId`,
+ * and presenting that as though it were the stored name would be a lie about
+ * the record. `stageReached` is the answer to the same question, computed
+ * server-side, and is what this page reads.
+ */
+export interface FunnelResultRow {
+  id: string;
+  entityId: string;
+  entityType: string;
+  matched: boolean;
+  excludedAtStage: string | null;
+  stageReached: StageReached | null;
+  exclusionReason?: string;
+  context?: Record<string, unknown>;
+  accumulatedTags?: string[];
+  createdAt: string;
+}
+
+/** The server-side narrowings the funnel list supports. */
+export interface FunnelListQuery {
+  status: FunnelStatus | '';
+  search: string;
+  page: number;
+}
+
+export interface FunnelsPageProps {
+  /**
+   * The funnel client, already bound to the path family of the surface that is
+   * mounting this page — `foundryTenantFunnelPaths(slug)` on the control plane,
+   * `proxiedCentralFunnelPaths('/central-api')` inside a fork. The page never
+   * builds a URL of its own; that is the whole point of the injection.
+   */
+  client: FunnelApiClient;
+
+  /**
+   * Where the rule vocabulary comes from. SEPARATE FROM `client` because the
+   * two are not on the same surface: `/fields/` is mounted ONLY on central
+   * (`/api/v1/funnels/fields/`, scoped to the caller's company), and the
+   * control plane's `funnels/fields/` is shadowed by its `funnels/<id>/`
+   * action and 404s. See the note on `foundryTenantFunnelPaths`.
+   *
+   * Defaults to `client`, which is right for any surface that does serve the
+   * endpoint under its own prefix.
+   */
+  fieldsClient?: FunnelApiClient;
+
+  /**
+   * Whether this viewer may create, edit and run funnels (`manage_funnels`).
+   * Read-only viewers (`view_funnels`) still get the list, the history and the
+   * results. The server enforces this either way — this only keeps the page
+   * from offering a button that will 403.
+   */
+  canManage?: boolean;
+
+  /** Rows per page for both tables. */
+  pageSize?: number;
+
+  className?: string;
+}