Building an Audience Builder UI

{
  "total_count": 42,
  "fields": [
    {
      "field_key": "seniority_level",
      "display_name": "Seniority Level",
      "category": "contact",
      "field_type": "multiselect",
      "operators": ["in", "notin"],
      "options": [
        { "value": "cxo", "label": "CXO" },
        { "value": "director", "label": "Director" },
        { "value": "manager", "label": "Manager" },
        { "value": "staff", "label": "Staff" },
        { "value": "vp", "label": "VP" }
      ],
      "sort_order": 12
    }
  ]
}

interface FieldCatalogEntry {
  field_key: string;
  display_name: string;
  category: string;
  field_type: "multiselect" | "select" | "text" | "number";
  operators: string[];
  options?: { value: string; label: string }[];
  sort_order: number;
}

function groupByCategory(fields: FieldCatalogEntry[]) {
  const groups: Record<string, FieldCatalogEntry[]> = {};
  for (const field of fields) {
    if (!groups[field.category]) groups[field.category] = [];
    groups[field.category].push(field);
  }
  for (const cat of Object.keys(groups)) {
    groups[cat].sort((a, b) => a.sort_order - b.sort_order);
  }
  return groups;
}

function renderMultiselect(field: FieldCatalogEntry) {
  return (
    <MultiSelect
      label={field.display_name}
      options={field.options.map(opt => ({
        value: opt.value,   // "cxo" - sent in filter rule
        label: opt.label,   // "CXO" - shown in UI
      }))}
      onChange={(selected) => updateRule(field.field_key, "in", selected)}
    />
  );
}

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["topic_id_1", "topic_id_2"]
        }
      },
      {
        "fieldName": "seniority_level",
        "conditionRules": {
          "operator": "in",
          "value": ["cxo", "vp", "director"]
        }
      }
    ]
  }
}

{
  "condition": "and",
  "rules": [
    {
      "fieldName": "INTENT",
      "conditionRules": { "operator": "in", "value": ["topic_123"] }
    },
    {
      "fieldName": "seniority_level",
      "conditionRules": { "operator": "in", "value": ["cxo", "vp", "director"] }
    },
    {
      "condition": "or",
      "rules": [
        {
          "fieldName": "company_industry",
          "conditionRules": { "operator": "contains", "value": "software" }
        },
        {
          "fieldName": "company_industry",
          "conditionRules": { "operator": "contains", "value": "internet" }
        }
      ]
    }
  ]
}

{
  "fieldName": "INTENT",
  "conditionRules": { "operator": "in", "value": ["4eyes_115481", "4eyes_119418"] }
}

{
  "fieldName": "score",
  "conditionRules": { "operator": "in", "value": ["high", "medium"] }
}

{
  "fieldName": "PERSONA",
  "conditionRules": { "operator": "in", "value": ["4738"] }
}

{
  "organization_id": "org_123",
  "project_id": "proj_456",
  "audience_name": "Enterprise VPs - Cloud Computing",
  "type": "intents",
  "segmentation_type": "Audience",
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": { "operator": "in", "value": ["4eyes_119418"] }
      },
      {
        "fieldName": "seniority_level",
        "conditionRules": { "operator": "in", "value": ["cxo", "vp", "director"] }
      },
      {
        "fieldName": "company_employee_count_range",
        "conditionRules": { "operator": "in", "value": ["1001 to 5000", "5001 to 10000", "10000+"] }
      }
    ]
  }
}

{
  "id": 8269,
  "status": "Pending",
  "audience_name": "Enterprise VPs - Cloud Computing",
  "type": "intents",
  "segmentation_type": "Audience"
}

async function pollAudienceStatus(token: string, audienceId: number, projectId: string) {
  while (true) {
    const resp = await fetch(
      `https://api.delivr.ai/api/v1/audiences/${audienceId}?project_id=${projectId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await resp.json();

    if (data.status === "Completed") return data;
    if (data.status === "Failed") throw new Error(data.error || "Audience processing failed");

    await new Promise((r) => setTimeout(r, 10_000));
  }
}

type DownloadPreparation = {
  status: string;
  // "ready" accompanies the ready response; the other four are preparation
  // stages. Widen with `| (string & {})` if you would rather not update the
  // union when a stage is added.
  stage?: "ready" | "waiting" | "building" | "deduplicating" | "finalizing";
  progress?: { completed: number; total: number };
  output_links?: Record<string, string[]>;
};

const RETRYABLE_HTTP_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);

class RetryableRequestError extends Error {}

function wait(ms: number, signal: AbortSignal) {
  if (signal.aborted) {
    return Promise.reject(
      signal.reason ?? new DOMException("Polling stopped", "AbortError"),
    );
  }

  return new Promise<void>((resolve, reject) => {
    const timer = setTimeout(finish, ms);

    function finish() {
      signal.removeEventListener("abort", cancel);
      resolve();
    }

    function cancel() {
      clearTimeout(timer);
      reject(signal.reason ?? new DOMException("Polling stopped", "AbortError"));
    }

    signal.addEventListener("abort", cancel, { once: true });
  });
}

async function fetchDownloadStatus(
  token: string,
  audienceId: number,
  projectId: string,
  signal: AbortSignal,
) {
  if (signal.aborted) {
    throw signal.reason ?? new DOMException("Polling stopped", "AbortError");
  }

  const requestController = new AbortController();
  let requestTimedOut = false;
  const cancelRequest = () => requestController.abort(signal.reason);
  const timeout = setTimeout(() => {
    requestTimedOut = true;
    requestController.abort();
  }, 15_000);

  signal.addEventListener("abort", cancelRequest, { once: true });

  try {
    const resp = await fetch(
      `https://api.delivr.ai/api/v1/audiences/${audienceId}/download?project_id=${projectId}`,
      {
        headers: { Authorization: `Bearer ${token}` },
        signal: requestController.signal,
      },
    );

    if (!resp.ok) {
      if (RETRYABLE_HTTP_STATUSES.has(resp.status)) {
        throw new RetryableRequestError(`Temporary HTTP ${resp.status}`);
      }
      throw new Error(`Download request failed with HTTP ${resp.status}`);
    }

    return (await resp.json()) as DownloadPreparation;
  } catch (error) {
    if (signal.aborted) {
      throw signal.reason ?? new DOMException("Polling stopped", "AbortError");
    }
    if (requestTimedOut) {
      throw new RetryableRequestError("Download status request timed out");
    }
    throw error;
  } finally {
    clearTimeout(timeout);
    signal.removeEventListener("abort", cancelRequest);
  }
}

async function pollFileStatus(
  token: string,
  audienceId: number,
  projectId: string,
  signal: AbortSignal,
  onProgress: (status: DownloadPreparation) => void,
) {
  let transientFailures = 0;

  while (!signal.aborted) {
    let data: DownloadPreparation;

    try {
      data = await fetchDownloadStatus(token, audienceId, projectId, signal);
      transientFailures = 0;
    } catch (error) {
      const retryable =
        error instanceof RetryableRequestError || error instanceof TypeError;
      if (!retryable) throw error;

      transientFailures += 1;
      const backoffMs = Math.min(1_000 * 2 ** (transientFailures - 1), 10_000);
      console.warn(`Download status unavailable; retrying in ${backoffMs}ms`, error);
      await wait(backoffMs, signal);
      continue;
    }

    onProgress(data);

    if (data.status === "ready") return data.output_links;
    if (data.status === "failed") throw new Error("File preparation failed");

    await wait(3_000, signal);
  }

  throw new DOMException("Polling stopped", "AbortError");
}

interface FieldOption { value: string; label: string }

interface CatalogField {
  field_key: string;
  display_name: string;
  category: string;
  field_type: "multiselect" | "select" | "text" | "number";
  operators: string[];
  options?: FieldOption[];
  sort_order: number;
}

interface FilterRule {
  fieldName: string;
  conditionRules: { operator: string; value: string | string[] };
}

interface FilterGroup {
  condition: "and" | "or";
  rules: (FilterRule | FilterGroup)[];
}

// 1. Fetch field catalog
async function fetchFields(token: string): Promise<CatalogField[]> {
  const resp = await fetch(
    "https://api.delivr.ai/api/v1/field-catalog?schema_type=audience&status=active&include_options=true",
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const data = await resp.json();
  return data.fields;
}

// 2. Build a filter rule from UI state
function buildRule(fieldKey: string, operator: string, value: string | string[]): FilterRule {
  return { fieldName: fieldKey, conditionRules: { operator, value } };
}

// 3. Assemble the filter tree
function buildFilter(
  intentTopicIds: string[],
  userRules: FilterRule[],
  scoreFilter?: string[]
): FilterGroup {
  const rules: (FilterRule | FilterGroup)[] = [
    buildRule("INTENT", "in", intentTopicIds),
  ];
  if (scoreFilter?.length) {
    rules.push(buildRule("score", "in", scoreFilter));
  }
  rules.push(...userRules);
  return { condition: "and", rules };
}

// 4. Submit to Audiences API
async function createAudience(
  token: string, orgId: string, projectId: string,
  name: string, filter: FilterGroup
) {
  const resp = await fetch(
    `https://api.delivr.ai/api/v1/audiences?project_id=${projectId}`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        organization_id: orgId,
        project_id: projectId,
        audience_name: name,
        type: "intents",
        segmentation_type: "Audience",
        filter,
      }),
    }
  );
  return resp.json();
}

// Usage
const fields = await fetchFields(token);
const contactFields = fields
  .filter(f => f.category === "contact")
  .sort((a, b) => a.sort_order - b.sort_order);

const seniorityRule = buildRule("seniority_level", "in", ["cxo", "vp"]);
const deptRule = buildRule("department", "in", ["engineering", "sales"]);

const filter = buildFilter(
  ["4eyes_119418", "4eyes_115481"],
  [seniorityRule, deptRule],
  ["high", "medium"]
);

const audience = await createAudience(token, orgId, projectId, "My Audience", filter);
// audience.id = 8269, audience.status = "Pending"