:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { Task } from "@posthog/shared/domain-types";
import { describe, expect, it, vi } from "vitest";
import { ApiRequestError, type FetchImplementation } from "./fetcher";
import {
CloudCommandError,
CloudUsageLimitError,
DESKTOP_BILLING_LIMIT_ERROR_CODE,
PostHogAPIClient,
ScoutRequestError,
SESSION_LOGS_PAGE_TIMEOUT_MS,
} from "./posthog-client";
describe("PostHogAPIClient", () => {
it.each(["implementation", "discussion"] as const)(
"creates a report %s without client repository credentials",
async (relationship) => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ id: "task-1" }), { status: 201 }),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await client.createSignalReportTask({
reportId: "report-1",
relationship,
description: "Read the report evidence",
title: "Review report",
question: " What caused this? ",
});
expect(fetch).toHaveBeenCalledOnce();
const [url, request] = fetch.mock.calls[0];
expect((url as URL).pathname).toBe("/api/projects/42/tasks/");
expect(request.method).toBe("POST");
expect(
(request.headers as Headers).get("X-PostHog-Client-Provenance"),
).toBe("posthog_desktop");
expect(JSON.parse(request.body)).toEqual({
description: "Read the report evidence",
title: "Review report",
origin_product: "signal_report",
signal_report: "report-1",
signal_report_task_relationship: relationship,
...(relationship === "discussion"
? { signal_report_discussion_question: "What caused this?" }
: {}),
});
},
);
it.each([
{ provenance: "posthog_mobile", action: "creates" },
{ provenance: "posthog_web", action: "creates" },
{ provenance: "posthog_mobile", action: "warms" },
{ provenance: "posthog_web", action: "warms" },
] as const)(
"sends $provenance provenance when it $action a task",
async ({ provenance, action }) => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
id: "task-1",
task_id: "task-1",
run_id: "run-1",
}),
{ status: 201 },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch, taskClientProvenance: provenance },
);
if (action === "creates") {
await client.createTask({ description: "Create a task" });
} else {
await client.warmTask({ repository: null, github_integration: null });
}
const request = fetch.mock.calls[0]?.[1];
expect(
(request?.headers as Headers).get("X-PostHog-Client-Provenance"),
).toBe(provenance);
},
);
it("shows the setup dependency error returned by the server", async () => {
const detail =
"The workflow action is unavailable. Sync templates and retry setup.";
const fetch = vi
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ detail }), { status: 503 }),
);
const client = new PostHogAPIClient(
"https://example.com",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.setupTaskChannel("channel-1", {
kind: "goal",
goal: {
statement: "Improve activation",
direction: "at_least",
period: "week",
},
}),
).rejects.toThrow(new Error(detail));
});
it.each([{}, { task_id: 123 }, { task_id: "invalid" }])(
"rejects an invalid setup response: %j",
async (body) => {
const fetch = vi
.fn()
.mockResolvedValue(new Response(JSON.stringify(body), { status: 201 }));
const client = new PostHogAPIClient(
"https://example.com",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.setupTaskChannel("channel-1", {
kind: "feature",
feature: { name: "Search" },
}),
).rejects.toThrow();
},
);
it("returns the validated setup task", async () => {
const body = { task_id: "0198cf5c-67dd-7000-8000-000000000001" };
const fetch = vi
.fn()
.mockResolvedValue(new Response(JSON.stringify(body), { status: 201 }));
const client = new PostHogAPIClient(
"https://example.com",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.setupTaskChannel("channel-1", {
kind: "feature",
feature: { name: "Search" },
}),
).resolves.toEqual(body);
});
describe("Desktop beta terms", () => {
it.each([
[
"checks acceptance",
"get",
(client: PostHogAPIClient) => client.areDesktopBetaTermsAccepted(),
],
[
"accepts terms",
"post",
(client: PostHogAPIClient) => client.acceptDesktopBetaTerms(),
],
] as const)(
"%s through the selected project",
async (_name, method, request) => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(
JSON.stringify({ is_desktop_beta_terms_accepted: true }),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await request(client);
expect(fetch).toHaveBeenCalledOnce();
expect((fetch.mock.calls[0][0] as URL).pathname).toBe(
"/api/projects/42/desktop_beta_terms/",
);
expect(fetch.mock.calls[0][1]).toMatchObject({
method: method.toUpperCase(),
});
},
);
});
it("sends the selected scout to the runs endpoint", async () => {
const fetch = vi
.fn()
.mockResolvedValue(new Response("[]", { status: 200 }));
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await client.listScoutRuns(42, { skill_name: "signals-scout-example" });
const url = fetch.mock.calls[0][0] as URL;
expect(url.pathname).toBe("/api/projects/42/signals/scout/runs/");
expect(url.searchParams.get("skill_name")).toBe("signals-scout-example");
});
describe("updateTaskChannelAutoArchive", () => {
it("rejects a successful response that did not save the setting", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ id: "channel-1", name: "personal" }), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.updateTaskChannelAutoArchive("channel-1", 7),
).rejects.toThrow(
"Automatic archiving isn't available on this server yet",
);
});
});
describe("setUserSpendLimit", () => {
// The shared fetcher throws on non-2xx, so the endpoint's `detail` must be
// unwrapped for the settings toast rather than the raw fetcher string.
it("surfaces the endpoint detail when the gateway rejects the limit", async () => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(
JSON.stringify({ detail: "Limit must be above current spend." }),
{ status: 400, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
const error = await client
.setUserSpendLimit(10, 30 * 24 * 60 * 60)
.catch((e: unknown) => e);
// The exact clean detail, not the raw `Failed request: [400] {...}`.
expect(error).toBeInstanceOf(Error);
expect((error as Error).message).toBe(
"Limit must be above current spend.",
);
});
});
describe("getLlmSkillByName", () => {
// The endpoint pages a body over 8,000 characters, so a single request
// returns instructions that stop mid-skill.
it("follows body_next_offset until the whole body is fetched", async () => {
const body = `${"x".repeat(8000)}final instruction`;
const fetch = vi.fn().mockImplementation((url: URL) => {
const offset = Number(url.searchParams.get("body_offset") ?? "0");
const page = body.slice(offset, offset + 8000);
const next = offset + 8000 < body.length ? offset + 8000 : null;
return Promise.resolve(
new Response(
JSON.stringify({
name: "pr-shepherd",
version: 3,
body: page,
body_total_length: body.length,
body_next_offset: next,
files: [],
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
});
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
const skill = await client.getLlmSkillByName("pr-shepherd");
expect(skill.body).toBe(body);
// The continuation pins the version, so a publish between pages cannot
// splice two bodies together.
const second = fetch.mock.calls[1][0] as URL;
expect(second.searchParams.get("body_offset")).toBe("8000");
expect(second.searchParams.get("version")).toBe("3");
});
it("rejects a body that arrives shorter than the server reports", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
name: "pr-shepherd",
version: 3,
body: "# Body",
body_total_length: 9689,
body_next_offset: null,
files: [],
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(client.getLlmSkillByName("pr-shepherd")).rejects.toThrow(
"got 6 of 9689 characters",
);
});
});
describe("getInsightDefinition", () => {
it("loads the saved insight with a blocking refresh and returns its result", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
id: 1,
short_id: "sdyR2Pn8",
name: "Unique users per variant",
derived_name: null,
description: "Feature flag calls",
query: { kind: "InsightVizNode", source: { kind: "TrendsQuery" } },
result: [
{
label: "$feature_flag_called - true",
data: [],
days: [],
aggregated_value: 2,
},
],
columns: null,
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(client.getInsightDefinition("sdyR2Pn8")).resolves.toEqual({
name: "Unique users per variant",
description: "Feature flag calls",
query: { kind: "InsightVizNode", source: { kind: "TrendsQuery" } },
response: {
results: [
{
label: "$feature_flag_called - true",
data: [],
days: [],
aggregated_value: 2,
},
],
columns: [],
},
});
const url = fetch.mock.calls[0][0] as URL;
expect(url.pathname).toBe("/api/projects/42/insights/sdyR2Pn8/");
expect(url.searchParams.get("refresh")).toBe("blocking");
});
it("returns null when the saved insight does not exist", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ detail: "Not found." }), {
status: 404,
headers: { "Content-Type": "application/json" },
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(client.getInsightDefinition("missing")).resolves.toBeNull();
});
});
describe("getInsightSummary", () => {
it("reads the insight from cache and falls back to its derived name", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
id: 1,
short_id: "sdyR2Pn8",
name: "",
derived_name: "Pageview count",
description: "",
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(client.getInsightSummary("sdyR2Pn8")).resolves.toEqual({
name: "Pageview count",
description: null,
});
const url = fetch.mock.calls[0][0] as URL;
expect(url.pathname).toBe("/api/projects/42/insights/sdyR2Pn8/");
expect(url.searchParams.get("basic")).toBe("true");
expect(url.searchParams.get("refresh")).toBe("force_cache");
});
});
describe("getEvidencePreview", () => {
it("retrieves an Inbox report from the signals endpoint", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
id: "rep-1",
title: "Checkout latency increased",
summary: "Requests became slower after the latest release.",
status: "ready",
priority: "P1",
signal_count: 3,
total_weight: 3,
artefact_count: 1,
created_at: "2026-01-02T10:00:00Z",
updated_at: "2026-01-03T10:00:00Z",
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.getEvidencePreview("report", "rep-1"),
).resolves.toMatchObject({
title: "Checkout latency increased",
status: { label: "Ready", tone: "positive" },
});
expect((fetch.mock.calls[0][0] as URL).pathname).toBe(
"/api/projects/42/signals/reports/rep-1/",
);
});
it("builds experiment presentation data from metric and exposure query responses", async () => {
const metricResponse = {
kind: "ExperimentQuery",
baseline: {
key: "control",
number_of_samples: 100,
sum: 10,
sum_squares: 10,
},
variant_results: [
{
key: "test",
method: "frequentist",
number_of_samples: 100,
sum: 12,
sum_squares: 12,
p_value: 0.04,
significant: true,
confidence_interval: [0.01, 0.39],
},
],
is_cached: true,
last_refresh: new Date().toISOString(),
};
const fetch = vi
.fn()
.mockResolvedValueOnce(
new Response(
JSON.stringify({
id: 1234,
name: "Checkout prompt",
feature_flag_key: "checkout-prompt",
feature_flag: { id: 3, key: "checkout-prompt" },
start_date: "2026-01-01T00:00:00Z",
metrics: [
{
kind: "ExperimentMetric",
uuid: "primary-1",
name: "Checkout conversion",
metric_type: "funnel",
},
],
metrics_secondary: [
{
kind: "ExperimentMetric",
uuid: "secondary-1",
name: "Orders per user",
metric_type: "mean",
},
],
saved_metrics: [],
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
)
.mockResolvedValueOnce(
new Response(
JSON.stringify({
kind: "ExperimentExposureQuery",
timeseries: [
{
variant: "control",
days: ["2026-01-01", "2026-01-02"],
exposure_counts: [45, 60],
},
{
variant: "test",
days: ["2026-01-01", "2026-01-02"],
exposure_counts: [43, 60],
},
],
total_exposures: { control: 105, test: 103 },
date_range: { date_from: "2026-01-01", date_to: null },
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
)
.mockResolvedValueOnce(
new Response(JSON.stringify(metricResponse), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify(metricResponse), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
const preview = await client.getEvidencePreview("experiment", "1234");
expect(preview).toMatchObject({
chart: {
title: "Daily exposures by variant",
labels: ["2026-01-01", "2026-01-02"],
series: [
{ label: "control", data: [45, 60] },
{ label: "test", data: [43, 60] },
],
render: "bar",
},
});
expect(preview?.experimentResults).toMatchObject({
state: "ready",
primaryMetrics: [
{
name: "Checkout conversion",
variants: [
expect.objectContaining({ key: "control" }),
expect.objectContaining({ key: "test", uplift: "+20.0%" }),
],
},
],
secondaryMetrics: [{ name: "Orders per user" }],
});
const queryBodies = fetch.mock.calls
.slice(1)
.map((call) => JSON.parse(String((call[1] as RequestInit).body)));
expect(queryBodies.map((body) => body.query.kind)).toEqual([
"ExperimentExposureQuery",
"ExperimentQuery",
"ExperimentQuery",
]);
expect(queryBodies.every((body) => body.refresh === undefined)).toBe(
true,
);
});
it("retrieves a person by UUID instead of taking the first search result", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
id: 1,
uuid: "0192aaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
name: "Ann",
distinct_ids: ["ann-1"],
properties: { email: "[email protected]" },
created_at: "2024-01-03T10:00:00Z",
last_seen_at: "2024-01-04T10:00:00Z",
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.getEvidencePreview(
"person",
"0192aaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
),
).resolves.toMatchObject({
title: "Ann",
resolvedId: "0192aaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
});
const url = fetch.mock.calls[0][0] as URL;
expect(url.pathname).toBe(
"/api/projects/42/persons/0192aaaa-bbbb-cccc-dddd-eeeeeeeeeeee/",
);
});
it("resolves a UUID-shaped distinct id when retrieve-by-uuid 404s", async () => {
const distinctId = "0192aaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
const fetch = vi
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ detail: "Not found." }), {
status: 404,
headers: { "Content-Type": "application/json" },
}),
)
.mockResolvedValueOnce(
new Response(
JSON.stringify({
results: [
{
id: 1,
uuid: "0192ffff-1111-2222-3333-444444444444",
name: "Ann",
distinct_ids: [distinctId],
properties: { email: "[email protected]" },
created_at: "2024-01-03T10:00:00Z",
last_seen_at: "2024-01-04T10:00:00Z",
},
],
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.getEvidencePreview("person", distinctId),
).resolves.toMatchObject({
title: "Ann",
resolvedId: "0192ffff-1111-2222-3333-444444444444",
});
expect((fetch.mock.calls[0][0] as URL).pathname).toBe(
`/api/projects/42/persons/${distinctId}/`,
);
const listUrl = fetch.mock.calls[1][0] as URL;
expect(listUrl.pathname).toBe("/api/projects/42/persons/");
expect(listUrl.searchParams.get("search")).toBe(distinctId);
});
});
it.each([
{
sources: ["posthog_desktop", "slack"],
sent: ["posthog_desktop", "slack"],
},
{ sources: [], sent: [] },
])("sends task list sources $sources as $sent", async ({ sources, sent }) => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ results: [], count: 0 }), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await client.getTasksPage({ sources });
const url = fetch.mock.calls[0][0] as URL;
expect(url.pathname).toBe("/api/projects/42/tasks/");
expect(url.searchParams.getAll("sources")).toEqual(sent);
});
it("fetches later task pages before reporting complete results", async () => {
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
);
const getTasksPage = vi
.spyOn(client, "getTasksPage")
.mockResolvedValueOnce({ tasks: [{ id: "task-1" } as Task], count: 2 })
.mockResolvedValueOnce({ tasks: [{ id: "task-2" } as Task], count: 2 });
await expect(
client.getTasksWithStatus(
{ repository: "posthog/posthog" },
{ maxPages: 2 },
),
).resolves.toMatchObject({
isComplete: true,
tasks: [{ id: "task-1" }, { id: "task-2" }],
});
expect(getTasksPage).toHaveBeenNthCalledWith(1, {
limit: 100,
offset: 0,
repository: "posthog/posthog",
});
expect(getTasksPage).toHaveBeenNthCalledWith(2, {
limit: 100,
offset: 1,
repository: "posthog/posthog",
});
});
it("reports partial task results after reaching the page cap", async () => {
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
);
vi.spyOn(client, "getTasksPage")
.mockResolvedValueOnce({ tasks: [{ id: "task-1" } as Task], count: 3 })
.mockResolvedValueOnce({ tasks: [{ id: "task-2" } as Task], count: 3 });
await expect(
client.getTasksWithStatus(undefined, { maxPages: 2 }),
).resolves.toMatchObject({
isComplete: false,
tasks: [{ id: "task-1" }, { id: "task-2" }],
});
});
it("fetches every task page when requested", async () => {
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
);
const getTasksPage = vi
.spyOn(client, "getTasksPage")
.mockResolvedValueOnce({ tasks: [{ id: "task-1" } as Task], count: 3 })
.mockResolvedValueOnce({ tasks: [{ id: "task-2" } as Task], count: 3 })
.mockResolvedValueOnce({ tasks: [{ id: "task-3" } as Task], count: 3 });
await expect(
client.getTasksWithStatus(undefined, { fetchAll: true }),
).resolves.toMatchObject({
isComplete: true,
tasks: [{ id: "task-1" }, { id: "task-2" }, { id: "task-3" }],
});
expect(getTasksPage).toHaveBeenCalledTimes(3);
});
it.each([
["pinned", { pinned: true }, "pinned", "true"],
["commented-by", { commentedBy: 17 }, "commented_by", "17"],
["mentions", { mentions: 19 }, "mentions", "19"],
["basic summary", { basic: true }, "basic", "true"],
])("sends the %s task-list filter", async (_name, options, param, value) => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ results: [], count: 0 }), {
status: 200,
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await client.getTasksPage(options);
const url = fetch.mock.calls[0][0] as URL;
expect(url.pathname).toBe("/api/projects/42/tasks/");
expect(url.searchParams.get(param)).toBe(value);
});
it.each([undefined, { basic: false }])(
"omits basic unless the caller asks for the summary payload (%o)",
async (options) => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ results: [], count: 0 }), {
status: 200,
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await client.getTasksPage(options);
const url = fetch.mock.calls[0][0] as URL;
expect(url.searchParams.has("basic")).toBe(false);
},
);
it.each([
"user_message",
"permission_response",
"set_config_option",
"cancel",
] as const)("sends the %s cloud run command", async (method) => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ result: { accepted: true } }), {
status: 200,
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.sendCloudRunCommand("task-1", "run-1", method, {
value: "payload",
}),
).resolves.toEqual({ accepted: true });
expect(fetch).toHaveBeenCalledWith(
new URL(
"https://app.posthog.test/api/projects/42/tasks/task-1/runs/run-1/command/",
),
expect.objectContaining({
method: "POST",
body: expect.any(String),
}),
);
const request = fetch.mock.calls[0][1] as RequestInit;
expect(JSON.parse(request.body as string)).toMatchObject({
jsonrpc: "2.0",
method,
params: { value: "payload" },
});
});
it("throws structured cloud command errors for HTTP failures", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({ error: "No active sandbox for this run" }),
{
status: 409,
statusText: "Conflict",
},
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
const error = await client
.sendCloudRunCommand("task-1", "run-1", "user_message")
.catch((caught: unknown) => caught);
expect(error).toMatchObject({
name: "CloudCommandError",
method: "user_message",
status: 409,
backendError: "No active sandbox for this run",
});
expect(error).toBeInstanceOf(CloudCommandError);
expect((error as CloudCommandError).isSandboxInactive()).toBe(true);
});
it("throws structured cloud command errors for JSON-RPC failures", async () => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(
JSON.stringify({ error: { message: "Permission request expired" } }),
{ status: 200 },
),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.sendCloudRunCommand("task-1", "run-1", "permission_response"),
).rejects.toMatchObject({
method: "permission_response",
status: 200,
backendError: "Permission request expired",
});
});
it("preserves the legacy sendRunCommand result contract", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ error: "Run is unavailable" }), {
status: 503,
}),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.sendRunCommand("task-1", "run-1", "set_config_option"),
).resolves.toEqual({
success: false,
error: "Cloud command 'set_config_option' failed: 503 Run is unavailable",
});
});
it("cancels a cloud task run with an optional reason", async () => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ status: "cancelled" }), { status: 200 }),
);
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(
client.cancelTaskRun("task-1", "run-1", "user requested"),
).resolves.toEqual({ status: "cancelled" });
expect(fetch).toHaveBeenCalledWith(
new URL(
"https://app.posthog.test/api/projects/42/tasks/task-1/runs/run-1/cancel/",
),
expect.objectContaining({
method: "POST",
body: JSON.stringify({ reason: "user requested" }),
}),
);
});
it("cancels a cloud task run with an empty body by default", async () => {
const fetch = vi
.fn()
.mockResolvedValue(new Response(null, { status: 204 }));
const client = new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
await expect(client.cancelTaskRun("task-1", "run-1")).resolves.toEqual({});
const request = fetch.mock.calls[0][1] as RequestInit;
expect(request.body).toBe(JSON.stringify({}));
});
it("builds cloud task config from the authenticated gateway catalog", async () => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
data: [
{
id: "claude-opus-4-8",
owned_by: "anthropic",
context_window: 200000,
supports_streaming: true,
supports_vision: true,
allowed: true,
},
{
id: "claude-fable-5",
owned_by: "anthropic",
context_window: 200000,
supports_streaming: true,
supports_vision: true,
allowed: false,
},
],
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://eu.posthog.com",
async () => "token",
async () => "token",
123,
{ fetch },
);
const options = await client.getCloudTaskConfigOptions("claude");
expect(fetch).toHaveBeenCalledWith(
new URL("https://gateway.eu.posthog.com/posthog_code/v1/models"),
expect.objectContaining({
method: "GET",
headers: expect.any(Headers),
}),
);
const requestHeaders = fetch.mock.calls[0]?.[1]?.headers as Headers;
expect(requestHeaders.get("X-PostHog-Project-Id")).toBe("123");
expect(options.find((option) => option.category === "model")).toMatchObject(
{
currentValue: "claude-opus-4-8",
options: [
expect.objectContaining({ value: "claude-opus-4-8" }),
expect.objectContaining({
value: "claude-fable-5",
_meta: expect.any(Object),
}),
],
},
);
});
it.each([
{
label: "desktop default",
options: undefined,
expectedConnectFrom: "posthog_code",
expectedUserAgent: "posthog/desktop.hog.dev; version: unknown",
},
{
label: "mobile configuration",
options: {
appVersion: "1.2.3",
userAgent: "posthog/mobile; version: 1.2.3",
githubConnectFrom: "posthog_mobile",
},
expectedConnectFrom: "posthog_mobile",
expectedUserAgent: "posthog/mobile; version: 1.2.3",
},
])(
"uses $label identity for GitHub connections",
async ({ options, expectedConnectFrom, expectedUserAgent }) => {
const fetch = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({ install_url: "https://github.com/login/oauth" }),
{
status: 200,
headers: { "Content-Type": "application/json" },
},
),
);
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
{ ...options, fetch },
);
await expect(client.startGithubUserIntegrationConnect()).resolves.toEqual(
{
install_url: "https://github.com/login/oauth",
},
);
expect(fetch).toHaveBeenCalledWith(
new URL(
"http://localhost:8000/api/users/@me/integrations/github/start/",
),
expect.objectContaining({
method: "POST",
body: JSON.stringify({
team_id: 123,
connect_from: expectedConnectFrom,
}),
}),
);
expect(fetch.mock.calls[0][1].headers.get("User-Agent")).toBe(
expectedUserAgent,
);
},
);
it("sends supported reasoning effort for cloud Codex runs", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/max-effort", {
adapter: "codex",
model: "gpt-5.4",
reasoningLevel: "high",
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
path: { project_id: "123", id: "task-123" },
body: expect.objectContaining({
mode: "interactive",
branch: "feature/max-effort",
runtime_adapter: "codex",
model: "gpt-5.4",
reasoning_effort: "high",
}),
}),
);
});
it("preserves Codex-native permission modes for cloud runs", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/codex-mode", {
adapter: "codex",
model: "gpt-5.4",
initialPermissionMode: "auto",
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.objectContaining({
initial_permission_mode: "auto",
}),
}),
);
});
it("preserves plan for cloud Codex runs", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/codex-plan", {
adapter: "codex",
model: "gpt-5.4",
initialPermissionMode: "plan",
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.objectContaining({
initial_permission_mode: "plan",
}),
}),
);
});
it.each([false, true])(
"omits the permission mode when no adapter is set (Pi: %s)",
async (piRuntime) => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/no-adapter", {
initialPermissionMode: "plan",
piRuntime,
claudeModelAccess: "own-subscription",
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.not.objectContaining({
initial_permission_mode: expect.anything(),
}),
}),
);
expect(post.mock.calls[0][1].body.claude_model_access).toBe(
piRuntime ? undefined : "own-subscription",
);
},
);
it.each([true, false])("forwards auto publish %s", async (autoPublish) => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", null, { autoPublish });
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.objectContaining({ auto_publish: autoPublish }),
}),
);
});
it("rejects unsupported reasoning effort for cloud Codex runs", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn();
(client as unknown as { api: { post: typeof post } }).api = { post };
await expect(
client.runTaskInCloud("task-123", "feature/max-effort", {
adapter: "codex",
model: "gpt-5.4",
reasoningLevel: "max",
}),
).rejects.toThrow(
"Reasoning effort 'max' is not supported for codex model 'gpt-5.4'.",
);
expect(post).not.toHaveBeenCalled();
});
it.each(["high", "max"] as const)(
"forwards supported GLM 5.2 reasoning effort %s",
async (reasoningLevel) => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({ id: "run-123" });
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/glm-effort", {
adapter: "claude",
model: "@cf/zai-org/glm-5.2",
reasoningLevel,
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.objectContaining({
runtime_adapter: "claude",
model: "@cf/zai-org/glm-5.2",
reasoning_effort: reasoningLevel,
}),
}),
);
},
);
it("rejects unsupported minimal reasoning effort for cloud runs", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn();
(client as unknown as { api: { post: typeof post } }).api = { post };
await expect(
client.runTaskInCloud("task-123", "feature/legacy-effort", {
adapter: "claude",
model: "claude-opus-4-8",
reasoningLevel: "minimal",
}),
).rejects.toThrow(
"Reasoning effort 'minimal' is not supported for claude model 'claude-opus-4-8'.",
);
expect(post).not.toHaveBeenCalled();
});
it("creates cloud task runs without relying on generated request typing", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ id: "run-123", environment: "cloud" }),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.createTaskRun("task-123", {
environment: "cloud",
mode: "interactive",
branch: "feature/direct-upload",
adapter: "codex",
model: "gpt-5.4",
reasoningLevel: "high",
initialPermissionMode: "auto",
}),
).resolves.toMatchObject({
id: "run-123",
task: "task-123",
team: 123,
environment: "cloud",
status: "not_started",
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "post",
path: "/api/projects/123/tasks/task-123/runs/",
overrides: {
body: JSON.stringify({
mode: "interactive",
branch: "feature/direct-upload",
runtime_adapter: "codex",
model: "gpt-5.4",
reasoning_effort: "high",
initial_permission_mode: "auto",
environment: "cloud",
}),
},
}),
);
});
it("loads native task session storage access", async () => {
const storage = {
id: "session-1",
download_url: "https://storage.example/session.jsonl",
content_sha256: "hash",
};
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => storage,
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.getTaskSessionStorageAccess("task-123", "run-123"),
).resolves.toEqual(storage);
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "get",
path: "/api/projects/123/tasks/task-123/runs/run-123/task_session/",
}),
);
});
it("maps the permission mode per adapter when creating task runs", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ id: "run-123", environment: "cloud" }),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await client.createTaskRun("task-123", {
environment: "cloud",
adapter: "claude",
model: "claude-opus-4-8",
initialPermissionMode: "read-only",
});
const body = JSON.parse(fetch.mock.calls[0][0].overrides.body as string);
expect(body.initial_permission_mode).toBe("plan");
});
it("serializes an rtk opt-out as rtk_enabled false on run creation", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ id: "run-123", environment: "cloud" }),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await client.createTaskRun("task-123", {
environment: "cloud",
mode: "interactive",
rtkEnabled: false,
});
const request = fetch.mock.calls[0][0] as {
overrides: { body: string };
};
expect(JSON.parse(request.overrides.body)).toMatchObject({
rtk_enabled: false,
});
});
it.each([false, true])(
"omits the permission mode from created task runs without an adapter (Pi: %s)",
async (piRuntime) => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ id: "run-123", environment: "cloud" }),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await client.createTaskRun("task-123", {
environment: "cloud",
initialPermissionMode: "plan",
piRuntime,
claudeModelAccess: "own-subscription",
});
const body = JSON.parse(fetch.mock.calls[0][0].overrides.body as string);
expect(body).not.toHaveProperty("initial_permission_mode");
expect(body.claude_model_access).toBe(
piRuntime ? undefined : "own-subscription",
);
},
);
it("omits the permission mode when none is selected", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/no-mode", {
adapter: "codex",
model: "gpt-5.4",
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.not.objectContaining({
initial_permission_mode: expect.anything(),
}),
}),
);
});
it("forwards contextWindow to the cloud run body when an adapter is set", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/context-window", {
adapter: "claude",
model: "claude-opus-5",
contextWindow: "1m",
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.objectContaining({ context_window: "1m" }),
}),
);
});
it.each([false, true] as const)(
"forwards fastMode:%s to the cloud run body when an adapter is set",
async (fastMode) => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/fast-mode", {
adapter: "claude",
model: "claude-opus-5",
fastMode,
});
expect(post).toHaveBeenCalledWith(
"/api/projects/{project_id}/tasks/{id}/run/",
expect.objectContaining({
body: expect.objectContaining({ fast_mode: fastMode }),
}),
);
},
);
it("omits contextWindow and fastMode when no adapter is set", async () => {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
const post = vi.fn().mockResolvedValue({
id: "task-123",
title: "Task",
description: "Task",
created_at: "2026-04-14T00:00:00Z",
updated_at: "2026-04-14T00:00:00Z",
origin_product: "user_created",
});
(client as unknown as { api: { post: typeof post } }).api = { post };
await client.runTaskInCloud("task-123", "feature/no-adapter", {
contextWindow: "1m",
fastMode: false,
});
const call = post.mock.calls[0][1] as { body: Record<string, unknown> };
expect(call.body).not.toHaveProperty("context_window");
expect(call.body).not.toHaveProperty("fast_mode");
});
it("starts an existing cloud task run with run-scoped artifact ids", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ id: "task-123", latest_run: { id: "run-123" } }),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.startTaskRun("task-123", "run-123", {
pendingUserMessage: "Read the attached file first",
pendingUserArtifactIds: ["artifact-1"],
}),
).resolves.toMatchObject({
id: "task-123",
latest_run: {
id: "run-123",
task: "task-123",
team: 123,
status: "not_started",
},
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "post",
path: "/api/projects/123/tasks/task-123/runs/run-123/start/",
overrides: {
body: JSON.stringify({
pending_user_message: "Read the attached file first",
pending_user_artifact_ids: ["artifact-1"],
}),
},
}),
);
});
it("registers PostHog references without file upload fields", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
artifacts: [
{
id: "phref-1",
name: "Checkout funnel",
type: "reference",
source: "posthog_object",
uploaded_at: "2026-08-19T00:00:00Z",
metadata: {
reference_type: "posthog_object",
object_kind: "insight",
object_id: "9pQx3",
source_message_ids: ["turn-1"],
occurrence_count: 1,
},
},
],
}),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.registerTaskRunPostHogReferences("task-123", "run-123", [
{
name: "Checkout funnel",
object_kind: "insight",
object_id: "9pQx3",
source_message_id: "turn-1",
},
]),
).resolves.toEqual([
expect.objectContaining({
id: "phref-1",
type: "reference",
source: "posthog_object",
metadata: expect.objectContaining({ object_id: "9pQx3" }),
}),
]);
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "post",
path: "/api/projects/123/tasks/task-123/runs/run-123/artifacts/references/",
overrides: {
body: JSON.stringify({
references: [
{
name: "Checkout funnel",
object_kind: "insight",
object_id: "9pQx3",
source_message_id: "turn-1",
},
],
}),
},
}),
);
});
it("presigns a task run artifact for preview", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
url: "https://s3.example.com/screenshot.png?signature=abc",
expires_in: 3600,
}),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.presignTaskRunArtifact(
"task-123",
"run-123",
"tasks/run-123/artifacts/screenshot.png",
),
).resolves.toBe("https://s3.example.com/screenshot.png?signature=abc");
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "post",
path: "/api/projects/123/tasks/task-123/runs/run-123/artifacts/presign/",
overrides: {
body: JSON.stringify({
storage_path: "tasks/run-123/artifacts/screenshot.png",
}),
},
}),
);
});
it("returns the redirect URL when authorizing an MCP installation", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
status: 200,
json: async () => ({
redirect_url: "https://auth.example.com/authorize?state=abc",
}),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.authorizeMcpInstallation({
installation_id: "inst-123",
install_source: "posthog-code",
posthog_code_callback_url: "posthog-code://mcp-oauth-complete",
}),
).resolves.toEqual({
redirect_url: "https://auth.example.com/authorize?state=abc",
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "get",
path: "/api/environments/123/mcp_server_installations/authorize/",
}),
);
expect(fetch.mock.calls[0][0]).not.toHaveProperty("overrides");
});
describe("warmTask", () => {
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
it("posts the repository + integration + branch and returns the warm run identifiers", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
text: async () =>
JSON.stringify({ task_id: "task-1", run_id: "run-1" }),
});
const client = makeClient(fetch);
await expect(
client.warmTask({
repository: "PostHog/posthog",
github_integration: 42,
branch: "feature/warm",
}),
).resolves.toEqual({ task_id: "task-1", run_id: "run-1" });
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "post",
path: "/api/projects/123/tasks/warm/",
overrides: {
body: JSON.stringify({
repository: "PostHog/posthog",
github_integration: 42,
branch: "feature/warm",
runtime_adapter: null,
model: null,
reasoning_effort: null,
initial_permission_mode: null,
}),
},
}),
);
});
it("forwards the selected runtime so the warm Run starts on it", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
text: async () =>
JSON.stringify({ task_id: "task-1", run_id: "run-1" }),
});
const client = makeClient(fetch);
await client.warmTask({
repository: "PostHog/posthog",
github_integration: 42,
branch: "feature/warm",
runtime_adapter: "codex",
model: "gpt-5.5",
reasoning_effort: "high",
initial_permission_mode: "auto",
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
overrides: {
body: JSON.stringify({
repository: "PostHog/posthog",
github_integration: 42,
branch: "feature/warm",
runtime_adapter: "codex",
model: "gpt-5.5",
reasoning_effort: "high",
initial_permission_mode: "auto",
}),
},
}),
);
});
it("forwards the selected sandbox environment and custom image", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
text: async () =>
JSON.stringify({ task_id: "task-1", run_id: "run-1" }),
});
const client = makeClient(fetch);
await client.warmTask({
repository: "PostHog/posthog",
github_integration: 42,
sandbox_environment_id: "environment-123",
custom_image_id: "image-123",
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
overrides: {
body: JSON.stringify({
repository: "PostHog/posthog",
github_integration: 42,
branch: null,
runtime_adapter: null,
model: null,
reasoning_effort: null,
initial_permission_mode: null,
sandbox_environment_id: "environment-123",
custom_image_id: "image-123",
}),
},
}),
);
});
it("sends a null branch when none is provided", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
text: async () =>
JSON.stringify({ task_id: "task-1", run_id: "run-1" }),
});
const client = makeClient(fetch);
await client.warmTask({
repository: "PostHog/posthog",
github_integration: 42,
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
overrides: {
body: JSON.stringify({
repository: "PostHog/posthog",
github_integration: 42,
branch: null,
runtime_adapter: null,
model: null,
reasoning_effort: null,
initial_permission_mode: null,
}),
},
}),
);
});
it("supports warming a repo-less sandbox", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
text: async () =>
JSON.stringify({ task_id: "task-1", run_id: "run-1" }),
});
const client = makeClient(fetch);
await client.warmTask({ repository: null, github_integration: null });
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
overrides: {
body: JSON.stringify({
repository: null,
github_integration: null,
branch: null,
runtime_adapter: null,
model: null,
reasoning_effort: null,
initial_permission_mode: null,
}),
},
}),
);
});
it("returns null on an empty 200 body (feature disabled / capped / no-op)", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
text: async () => "",
});
const client = makeClient(fetch);
await expect(
client.warmTask({
repository: "PostHog/posthog",
github_integration: 42,
}),
).resolves.toBeNull();
});
it("throws on a non-ok response", async () => {
const fetch = vi
.fn()
.mockResolvedValue({ ok: false, statusText: "Bad Request" });
const client = makeClient(fetch);
await expect(
client.warmTask({
repository: "PostHog/posthog",
github_integration: 42,
}),
).rejects.toThrow("Bad Request");
});
it("maps the Desktop billing denial to a cloud usage limit", async () => {
const body = {
type: "rate_limit",
code: DESKTOP_BILLING_LIMIT_ERROR_CODE,
detail: "Your organization reached its PostHog Desktop usage limit.",
};
const fetch = vi
.fn()
.mockRejectedValue(
new ApiRequestError(429, JSON.stringify(body), body),
);
const client = makeClient(fetch);
await expect(
client.warmTask({ repository: null, github_integration: null }),
).rejects.toBeInstanceOf(CloudUsageLimitError);
});
it("does not map unrelated 429 responses to billing", async () => {
const body = { code: "another_rate_limit" };
const error = new ApiRequestError(429, JSON.stringify(body), body);
const client = makeClient(vi.fn().mockRejectedValue(error));
await expect(
client.warmTask({ repository: null, github_integration: null }),
).rejects.toBe(error);
});
});
describe("getSignalReports", () => {
it("sends report filters to the reports endpoint", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ count: 3, results: [] }),
});
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
await expect(
client.getSignalReports({
actionability: "immediately_actionable,requires_human_input",
count_only: true,
}),
).resolves.toEqual({ count: 3, results: [] });
const request = fetch.mock.calls[0]?.[0] as { url: URL };
expect(request.url.toString()).toBe(
"http://localhost:8000/api/projects/123/signals/reports/?actionability=immediately_actionable%2Crequires_human_input&count_only=true",
);
});
});
describe("getSignalReport", () => {
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
return client;
}
it("returns the parsed report on success", async () => {
const fetch = vi.fn().mockResolvedValue({
json: async () => ({ id: "abc", title: "hi" }),
});
const client = makeClient(fetch);
await expect(client.getSignalReport("abc")).resolves.toEqual({
id: "abc",
title: "hi",
});
});
it("returns null when the shared fetcher throws a 404", async () => {
const fetch = vi
.fn()
.mockRejectedValue(
new Error('Failed request: [404] {"detail":"Not found."}'),
);
const client = makeClient(fetch);
await expect(client.getSignalReport("abc")).resolves.toBeNull();
});
it("returns null when the shared fetcher throws a 403", async () => {
const fetch = vi
.fn()
.mockRejectedValue(
new Error('Failed request: [403] {"detail":"Forbidden."}'),
);
const client = makeClient(fetch);
await expect(client.getSignalReport("abc")).resolves.toBeNull();
});
it("rethrows non-404/403 errors", async () => {
const fetch = vi
.fn()
.mockRejectedValue(new Error("Failed request: [500] boom"));
const client = makeClient(fetch);
await expect(client.getSignalReport("abc")).rejects.toThrow("[500]");
});
});
describe("updateSignalReportState", () => {
function makeClient(fetch: FetchImplementation): PostHogAPIClient {
return new PostHogAPIClient(
"https://app.posthog.test",
async () => "token",
async () => "token",
42,
{ fetch },
);
}
it("accepts a suppression conflict when a fresh read is already suppressed", async () => {
const fetch = vi
.fn<FetchImplementation>()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: "Invalid state transition" }), {
status: 409,
headers: { "Content-Type": "application/json" },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ id: "abc", status: "suppressed" }), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
const client = makeClient(fetch);
await expect(
client.updateSignalReportState("abc", { state: "suppressed" }),
).resolves.toMatchObject({ id: "abc", status: "suppressed" });
});
it("preserves a suppression conflict when the report is still active", async () => {
const fetch = vi
.fn<FetchImplementation>()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: "Invalid state transition" }), {
status: 409,
headers: { "Content-Type": "application/json" },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ id: "abc", status: "ready" }), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
const client = makeClient(fetch);
await expect(
client.updateSignalReportState("abc", { state: "suppressed" }),
).rejects.toThrow("[409]");
});
it.each([
{
name: "accepts matching dismissal feedback",
current: {
dismissal_reason: "wontfix_intentional",
dismissal_note: "Expected behavior",
},
rejects: false,
},
{
name: "rejects feedback another dismissal did not save",
current: {
dismissal_reason: "analysis_wrong",
dismissal_note: "Different feedback",
},
rejects: true,
},
])("$name after a suppression conflict", async ({ current, rejects }) => {
const fetch = vi
.fn<FetchImplementation>()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: "Invalid state transition" }), {
status: 409,
headers: { "Content-Type": "application/json" },
}),
)
.mockResolvedValueOnce(
new Response(
JSON.stringify({ id: "abc", status: "suppressed", ...current }),
{
status: 200,
headers: { "Content-Type": "application/json" },
},
),
);
const request = makeClient(fetch).updateSignalReportState("abc", {
state: "suppressed",
dismissal_reason: "wontfix_intentional",
dismissal_note: " Expected behavior ",
});
if (rejects) {
await expect(request).rejects.toThrow("[409]");
} else {
await expect(request).resolves.toMatchObject({ status: "suppressed" });
}
});
});
describe("clearTaskRunConversation", () => {
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
return client;
}
it("surfaces the backend's clean error message", async () => {
const fetch = vi
.fn()
.mockRejectedValue(
new Error(
'Failed request: [409] {"error":"Run is still active; send /clear to its agent instead"}',
),
);
const client = makeClient(fetch);
await expect(
client.clearTaskRunConversation("task-1", "run-1"),
).rejects.toThrow(
"Run is still active; send /clear to its agent instead",
);
});
it("falls back to a status-coded message on an older backend's generic 404", async () => {
// A pre-#76943 backend has no clear_conversation route, so DRF's router
// returns its generic {"detail":"Not found."} rather than a message
// this endpoint controls. Surfacing that verbatim would read as "Not
// found." with no indication a clear was attempted or what to do next.
const fetch = vi
.fn()
.mockRejectedValue(
new Error('Failed request: [404] {"detail":"Not found."}'),
);
const client = makeClient(fetch);
await expect(
client.clearTaskRunConversation("task-1", "run-1"),
).rejects.toThrow("Couldn’t clear the conversation. (HTTP 404)");
});
});
describe("getTaskSummaries", () => {
const SUMMARIES_PATH = "/api/projects/123/tasks/summaries/";
function buildClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
function page(results: object[], count: number = results.length) {
return {
ok: true,
json: async () => ({ count, previous: null, next: null, results }),
};
}
function buildFetchForPages(...pages: ReturnType<typeof page>[]) {
const fetch = vi.fn();
for (const p of pages) fetch.mockResolvedValueOnce(p);
return fetch;
}
it("returns immediately for empty input without hitting the network", async () => {
const fetch = vi.fn();
await expect(buildClient(fetch).getTaskSummaries([])).resolves.toEqual(
[],
);
expect(fetch).not.toHaveBeenCalled();
});
it("requests the max page size and stops when one page covers the count", async () => {
const fetch = buildFetchForPages(page([{ id: "a" }]));
await expect(buildClient(fetch).getTaskSummaries(["a"])).resolves.toEqual(
[{ id: "a" }],
);
expect(fetch).toHaveBeenCalledTimes(1);
expect(fetch.mock.calls[0][0]).toMatchObject({
method: "post",
path: `${SUMMARIES_PATH}?limit=100&offset=0`,
});
});
it.each([
{},
{ pr_url: null, pr_state: null },
{
pr_url: "https://github.com/example/project/pull/1",
pr_state: "merged",
},
])("preserves optional PR fields in task summaries: %j", async (fields) => {
const summary = {
id: "task-1",
latest_run: { id: "run-1", status: "completed", ...fields },
};
const fetch = buildFetchForPages(page([summary]));
const summaries = await buildClient(fetch).getTaskSummaries([summary.id]);
expect(summaries).toEqual([summary]);
expect(summaries[0].latest_run?.pr_url).toBe(fields.pr_url);
expect(summaries[0].latest_run?.pr_state).toBe(fields.pr_state);
});
it("fetches remaining pages by offset from count, not by walking next", async () => {
const fetch = buildFetchForPages(
page([{ id: "a" }], 250),
page([{ id: "b" }]),
page([{ id: "c" }]),
);
await expect(
buildClient(fetch).getTaskSummaries(["a", "b", "c"]),
).resolves.toEqual([{ id: "a" }, { id: "b" }, { id: "c" }]);
expect(fetch).toHaveBeenCalledTimes(3);
expect(fetch.mock.calls.map((call) => call[0].path)).toEqual([
`${SUMMARIES_PATH}?limit=100&offset=0`,
`${SUMMARIES_PATH}?limit=100&offset=100`,
`${SUMMARIES_PATH}?limit=100&offset=200`,
]);
});
it("throws when the server responds non-OK", async () => {
const fetch = vi
.fn()
.mockResolvedValue({ ok: false, statusText: "Bad Request" });
await expect(buildClient(fetch).getTaskSummaries(["a"])).rejects.toThrow(
"Bad Request",
);
});
it("caps at MAX_PAGES when the count is unbounded", async () => {
const fetch = vi.fn().mockResolvedValue(page([{ id: "x" }], 1_000_000));
const result = await buildClient(fetch).getTaskSummaries(["a"]);
expect(fetch).toHaveBeenCalledTimes(50);
expect(result.length).toBe(50);
});
it("caps how many page fetches are in flight at once", async () => {
let inFlight = 0;
let maxInFlight = 0;
const fetch = vi.fn().mockImplementation(async () => {
inFlight++;
maxInFlight = Math.max(maxInFlight, inFlight);
await Promise.resolve();
inFlight--;
return page([{ id: "x" }], 2000);
});
await buildClient(fetch).getTaskSummaries(["a"]);
// 20 pages (count 2000 / 100), fetched in bounded batches, never all at once.
expect(fetch).toHaveBeenCalledTimes(20);
expect(maxInFlight).toBeLessThanOrEqual(6);
});
});
describe("task pins", () => {
function buildClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
it("loads pinned task ids", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ task_ids: ["task-1", "task-2"] }),
});
await expect(buildClient(fetch).getPinnedTaskIds()).resolves.toEqual([
"task-1",
"task-2",
]);
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "get",
path: "/api/projects/123/tasks/pinned/",
}),
);
});
it("sets pin state idempotently", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ task_id: "task-1", pinned: true }),
});
await expect(
buildClient(fetch).setTaskPinned("task-1", true),
).resolves.toBe(true);
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "post",
path: "/api/projects/123/tasks/task-1/pin/",
overrides: { body: JSON.stringify({ pinned: true }) },
}),
);
});
});
describe("getSignalReportArtefacts", () => {
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = {
baseUrl: "http://localhost:8000",
fetcher: { fetch },
};
return client;
}
// One row per backend ArtefactType (products/signals/backend/models.py),
// content shapes mirroring artefact_schemas.py / real API payloads.
const ROWS = [
{
id: "a1",
type: "video_segment",
content: {
session_id: "s1",
start_time: "2026-06-01T00:00:00Z",
end_time: "2026-06-01T00:01:00Z",
distinct_id: "d1",
content: "user rage-clicked the save button",
distance_to_centroid: 0.1,
},
created_at: "2026-06-01T00:00:00Z",
},
{
id: "a2",
type: "safety_judgment",
content: { choice: true, explanation: "No prompt injection found." },
created_at: "2026-06-01T00:00:01Z",
task_id: "t1",
},
{
id: "a3",
type: "actionability_judgment",
content: {
explanation: "Clear repro and code path.",
actionability: "immediately_actionable",
already_addressed: false,
},
created_at: "2026-06-01T00:00:02Z",
},
{
id: "a4",
type: "priority_judgment",
content: { explanation: "Cosmetic race.", priority: "P3" },
created_at: "2026-06-01T00:00:03Z",
},
{
id: "a5",
type: "signal_finding",
content: {
signal_id: "sig-1",
relevant_code_paths: ["a.ts"],
relevant_commit_hashes: { abc1234: "introduced the bug" },
data_queried: "execute-sql",
verified: true,
},
created_at: "2026-06-01T00:00:04Z",
},
{
id: "a6",
type: "repo_selection",
content: { repository: "posthog/posthog", reason: "Caller provided." },
created_at: "2026-06-01T00:00:05Z",
},
{
id: "a7",
type: "suggested_reviewers",
content: [
{
github_login: "octocat",
github_name: "Octo Cat",
relevant_commits: [],
user: null,
},
],
created_at: "2026-06-01T00:00:06Z",
},
{
id: "a8",
type: "dismissal",
content: {
reason: "already_fixed",
note: "",
user_id: 1,
user_uuid: null,
},
created_at: "2026-06-01T00:00:07Z",
},
{
id: "a9",
type: "code_reference",
content: {
file_path: "src/a.ts",
start_line: 1,
end_line: 3,
contents: "let x = 1",
relevance_note: "origin",
},
created_at: "2026-06-01T00:00:08Z",
},
{
id: "a11",
type: "line_reference",
content: {
file_path: "src/a.ts",
line: 2,
note: "here",
contents: "x++",
},
created_at: "2026-06-01T00:00:10Z",
},
{
id: "a12",
type: "commit",
content: {
repository: "posthog/posthog",
branch: "main",
commit_sha: "abc1234",
message: "fix",
note: null,
},
created_at: "2026-06-01T00:00:11Z",
},
{
id: "a13",
type: "task_run",
content: { task_id: "t1", product: "tasks", type: "agent_run" },
created_at: "2026-06-01T00:00:12Z",
task_id: "t1",
},
{
id: "a14",
type: "note",
content: { note: "Guinea-pig probe note." },
created_at: "2026-06-01T00:00:13Z",
task_id: "t1",
created_by: null,
},
{
id: "a15",
type: "work_claim",
content: { display_name: "Ada" },
created_at: "2026-06-01T00:00:14Z",
},
{
id: "a16",
type: "work_release",
content: { reason: "taken_over" },
created_at: "2026-06-01T00:00:15Z",
},
{
id: "a17",
type: "ranking_score",
content: {
scored_at: "2026-06-01T00:00:16Z",
manifest_version: "12",
served_key: "report_embeddings@2026-05-31",
results: {
"signal_counts@2026-05-31": {
status: "skipped",
roles: ["challenger"],
skip_reason: "missing report vector",
scores: {},
},
"report_embeddings@2026-05-31": {
status: "scored",
roles: ["served"],
scores: { pr_merged: 0.52, action: 0.78, refund: 0.04 },
lifts: { action: 1.3 },
metadata: {
heads: [
{
head: "action",
readable: true,
refit_classification_threshold: 0.6,
},
{
head: "pr_merged",
readable: true,
refit_classification_threshold: 0.2,
},
{
head: "refund",
readable: false,
refit_classification_threshold: 0,
},
],
},
},
},
},
created_at: "2026-06-01T00:00:16Z",
},
];
it("normalizes every backend artefact type without dropping rows", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ count: ROWS.length, results: ROWS }),
});
const client = makeClient(fetch);
const { results, unavailableReason } =
await client.getSignalReportArtefacts("r1");
expect(unavailableReason).toBeUndefined();
expect(results.map((a) => a.id)).toEqual(ROWS.map((r) => r.id));
expect(results.map((a) => a.type)).toEqual(ROWS.map((r) => r.type));
expect(results.every((a) => !a.degraded)).toBe(true);
expect(results.at(-1)?.content).toEqual({
scored_at: "2026-06-01T00:00:16Z",
manifest_version: "12",
served: {
key: "report_embeddings@2026-05-31",
roles: ["served"],
status: "scored",
skip_reason: null,
// Stored lifts win, older rows derive lift from a positive base rate,
// and a head without one sorts last.
heads: [
{ name: "pr_merged", probability: 0.52, lift: 2.6, readable: true },
{ name: "action", probability: 0.78, lift: 1.3, readable: true },
{ name: "refund", probability: 0.04, lift: null, readable: false },
],
},
challengers: [
{
key: "signal_counts@2026-05-31",
roles: ["challenger"],
status: "skipped",
skip_reason: "missing report vector",
heads: [],
},
],
});
});
it("keeps rows whose content does not match the type's shape as degraded previews", async () => {
const rows = [
// commit missing branch/sha — must not vanish
{
id: "bad1",
type: "commit",
content: { repository: "posthog/posthog", message: "where am I" },
created_at: "2026-06-01T00:00:00Z",
task_id: "t1",
},
// unknown future type with arbitrary object content
{
id: "bad2",
type: "deploy_event",
content: { reason: "rolled back v2" },
created_at: "2026-06-01T00:00:01Z",
},
// empty content
{
id: "bad3",
type: "note",
content: {},
created_at: "2026-06-01T00:00:02Z",
},
// served model missing from the results
{
id: "bad4",
type: "ranking_score",
content: { served_key: "gone@1", results: {} },
created_at: "2026-06-01T00:00:03Z",
},
];
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ count: rows.length, results: rows }),
});
const client = makeClient(fetch);
const { results } = await client.getSignalReportArtefacts("r1");
expect(results.map((a) => a.id)).toEqual([
"bad1",
"bad2",
"bad3",
"bad4",
]);
expect(results.every((a) => a.degraded)).toBe(true);
expect(results[0].type).toBe("commit");
expect((results[1].content as { content: string }).content).toBe(
"rolled back v2",
);
// attribution survives the fallback path
expect(results[0].task_id).toBe("t1");
});
// A resolve stores its rationale as a `dismissal` artefact, so resolve-only
// reasons must normalize as dismissals rather than degrade to a raw preview.
it.each([["fixed_outside_posthog"], ["pr_merged"], ["no_action_needed"]])(
"keeps a resolve reason %s as a dismissal row",
async (reason) => {
const rows = [
{
id: "d1",
type: "dismissal",
content: {
state: "resolved",
reason,
note: "",
user_id: 1,
user_uuid: null,
},
created_at: "2026-06-01T00:00:00Z",
},
];
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ count: rows.length, results: rows }),
});
const client = makeClient(fetch);
const { results } = await client.getSignalReportArtefacts("r1");
expect(results).toHaveLength(1);
expect(results[0].type).toBe("dismissal");
expect(results[0].degraded).toBeFalsy();
expect((results[0].content as { reason: string }).reason).toBe(reason);
expect((results[0].content as { state: string }).state).toBe(
"resolved",
);
},
);
it.each([
[
"asks for the full log when a caller reads every row",
{ limit: 1000 },
"1000",
],
["leaves list callers on the server page size", undefined, null],
])("%s", async (_name, options, expected) => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ count: 0, results: [] }),
});
const client = makeClient(fetch);
await client.getSignalReportArtefacts("r1", options);
const { url } = fetch.mock.calls[0][0] as { url: URL };
expect(url.searchParams.get("limit")).toBe(expected);
});
});
describe("updateSignalReportArtefact", () => {
const ARTEFACT_PATH =
"/api/projects/123/signals/reports/report-1/artefacts/art-1/";
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
const OCTOCAT_REVIEWER = {
github_login: "octocat",
github_name: "The Octocat",
relevant_commits: [],
user: null,
};
it.each([
{
name: "adds only the target and keeps the full list for older servers",
edit: { action: "add" as const, targets: [{ user_uuid: "uuid-1" }] },
input: [{ github_login: "octocat" }, { user_uuid: "uuid-1" }],
responseContent: [OCTOCAT_REVIEWER],
},
{
name: "removes only the target with an empty legacy fallback",
edit: {
action: "remove" as const,
targets: [{ github_login: "octocat" }],
},
input: [],
responseContent: [],
},
])("$name", async ({ input, responseContent, edit }) => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
id: "art-1",
type: "suggested_reviewers",
created_at: "2024-01-01T00:00:00Z",
content: responseContent,
}),
});
const client = makeClient(fetch);
const result = await client.updateSignalReportArtefact(
"report-1",
"art-1",
input,
edit,
);
expect(result.type).toBe("suggested_reviewers");
expect(result.content).toEqual(responseContent);
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "put",
path: ARTEFACT_PATH,
overrides: { body: JSON.stringify({ content: input, ...edit }) },
}),
);
});
it("throws with the server message on a non-ok response", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: false,
text: async () =>
'{"error":"Only suggested_reviewers artefacts may be modified via this endpoint."}',
});
const client = makeClient(fetch);
await expect(
client.updateSignalReportArtefact("report-1", "art-1", [], {
action: "remove",
targets: [{ github_login: "octocat" }],
}),
).rejects.toThrow("Only suggested_reviewers");
});
it("throws when the response is not a suggested_reviewers artefact", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
id: "art-1",
type: "dismissal",
created_at: "2024-01-01T00:00:00Z",
content: { reason: "noise", note: "" },
}),
});
const client = makeClient(fetch);
await expect(
client.updateSignalReportArtefact("report-1", "art-1", [], {
action: "remove",
targets: [{ github_login: "octocat" }],
}),
).rejects.toThrow("Unexpected response");
});
it("sets the first reviewer through the report-level endpoint", async () => {
const content = [{ user_uuid: "uuid-1" }];
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
id: "art-1",
type: "suggested_reviewers",
created_at: "2024-01-01T00:00:00Z",
content: [OCTOCAT_REVIEWER],
}),
});
const client = makeClient(fetch);
await client.setSignalReportReviewers("report-1", content, {
action: "add",
targets: content,
});
expect(fetch).toHaveBeenCalledWith(
expect.objectContaining({
method: "put",
path: "/api/projects/123/signals/reports/report-1/reviewers/",
overrides: {
body: JSON.stringify({ content, action: "add", targets: content }),
},
}),
);
});
});
describe("batched scout emissions", () => {
const EMISSIONS_PATH =
"/api/projects/123/signals/scout/runs/emissions/batch/";
const REPORTS_PATH =
"/api/projects/123/signals/scout/runs/emissions/reports/batch/";
function buildClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
// Both batch methods share the same scoutBatchByRunIds helper, so their
// empty short-circuit, request shape, and error path are exercised together.
const methods = [
["batchScoutRunEmissions", EMISSIONS_PATH],
["batchScoutEmissionReports", REPORTS_PATH],
] as const;
it.each(methods)(
"%s short-circuits empty run ids without hitting the network",
async (method) => {
const fetch = vi.fn();
const client = buildClient(fetch);
await expect(client[method](123, [])).resolves.toEqual([]);
expect(fetch).not.toHaveBeenCalled();
},
);
it.each(methods)(
"%s POSTs the run ids in one request and flattens the response",
async (method, path) => {
const rows = [
{ id: "e1", run_id: "r1" },
{ id: "e2", run_id: "r2" },
];
const fetch = vi
.fn()
.mockResolvedValue({ ok: true, json: async () => rows });
await expect(
buildClient(fetch)[method](123, ["r1", "r2"]),
).resolves.toEqual(rows);
expect(fetch).toHaveBeenCalledTimes(1);
expect(fetch.mock.calls[0][0]).toMatchObject({ method: "post", path });
expect(JSON.parse(fetch.mock.calls[0][0].overrides.body)).toEqual({
run_ids: ["r1", "r2"],
});
},
);
it.each(methods)(
"%s throws when the server responds non-OK",
async (method) => {
const fetch = vi
.fn()
.mockResolvedValue({ ok: false, statusText: "Bad Request" });
await expect(buildClient(fetch)[method](123, ["r1"])).rejects.toThrow(
"Bad Request",
);
},
);
it("unwraps a paginated reports payload", async () => {
const links = [{ finding_id: "f1", source_id: "s1", report: null }];
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ results: links }),
});
await expect(
buildClient(fetch).batchScoutEmissionReports(123, ["r1"]),
).resolves.toEqual(links);
expect(fetch.mock.calls[0][0]).toMatchObject({
method: "post",
path: REPORTS_PATH,
});
});
it("splits >200 run ids into parallel chunks and concatenates them", async () => {
const runIds = Array.from({ length: 450 }, (_, i) => `r${i}`);
const fetch = vi.fn(async (req) => {
const { run_ids } = JSON.parse(req.overrides.body) as {
run_ids: string[];
};
return {
ok: true,
json: async () => run_ids.map((run_id) => ({ id: run_id, run_id })),
};
});
const result = await buildClient(fetch).batchScoutRunEmissions(
123,
runIds,
);
// 450 ids → chunks of 200, 200, 50.
expect(fetch).toHaveBeenCalledTimes(3);
expect(result).toHaveLength(450);
expect(result.map((row) => row.run_id)).toEqual(runIds);
});
});
describe("getTaskRunSessionLogsResult", () => {
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
function makeEntries(count: number, prefix: string) {
return Array.from({ length: count }, (_, i) => ({
type: "notification",
timestamp: `2026-07-01T00:00:00.${String(i).padStart(3, "0")}Z`,
notification: { method: `${prefix}-${i}` },
}));
}
function page(
entries: unknown[],
hasMore: boolean,
matchingCount?: number,
) {
const headers = new Headers({ "X-Has-More": String(hasMore) });
if (matchingCount !== undefined) {
headers.set("X-Matching-Count", String(matchingCount));
}
return {
ok: true,
json: async () => entries,
headers,
};
}
function requestedParams(call: { url: URL }) {
return Object.fromEntries(call.url.searchParams);
}
it.each([
{
name: "defaults to the server's max page size",
options: undefined,
expectedLimit: "5000",
},
{
name: "clamps a larger total cap to the server's max page size",
options: { limit: 100000 },
expectedLimit: "5000",
},
{
name: "requests fewer when the total cap is below the page size",
options: { limit: 100 },
expectedLimit: "100",
},
])("$name", async ({ options, expectedLimit }) => {
const fetch = vi.fn().mockResolvedValue(page(makeEntries(3, "a"), false));
const client = makeClient(fetch);
const result = (
await client.getTaskRunSessionLogsResult("task-1", "run-1", options)
).entries;
expect(result).toHaveLength(3);
expect(fetch).toHaveBeenCalledTimes(1);
expect(requestedParams(fetch.mock.calls[0][0])).toEqual({
limit: expectedLimit,
});
});
it("paginates until X-Has-More is false, advancing offset by entries actually returned", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(120, "a"), true))
.mockResolvedValueOnce(page(makeEntries(80, "b"), true))
.mockResolvedValueOnce(page(makeEntries(10, "c"), false));
const client = makeClient(fetch);
const result = (
await client.getTaskRunSessionLogsResult("task-1", "run-1", {
limit: 100000,
})
).entries;
expect(result).toHaveLength(210);
expect(fetch).toHaveBeenCalledTimes(3);
expect(requestedParams(fetch.mock.calls[1][0])).toEqual({
limit: "5000",
offset: "120",
});
expect(requestedParams(fetch.mock.calls[2][0])).toEqual({
limit: "5000",
offset: "200",
});
});
it("stops at the requested total limit even when more pages remain", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(5000, "a"), true))
.mockResolvedValueOnce(page(makeEntries(1000, "b"), true));
const client = makeClient(fetch);
const result = (
await client.getTaskRunSessionLogsResult("task-1", "run-1", {
limit: 6000,
})
).entries;
expect(result).toHaveLength(6000);
expect(fetch).toHaveBeenCalledTimes(2);
expect(requestedParams(fetch.mock.calls[1][0])).toEqual({
limit: "1000",
offset: "5000",
});
});
it("forwards the after cursor on every page", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(10, "a"), true))
.mockResolvedValueOnce(page(makeEntries(5, "b"), false));
const client = makeClient(fetch);
await client.getTaskRunSessionLogsResult("task-1", "run-1", {
limit: 100000,
after: "2026-07-01T00:00:00Z",
});
expect(requestedParams(fetch.mock.calls[0][0])).toEqual({
limit: "5000",
after: "2026-07-01T00:00:00Z",
});
expect(requestedParams(fetch.mock.calls[1][0])).toEqual({
limit: "5000",
offset: "10",
after: "2026-07-01T00:00:00Z",
});
});
it("fetches the newest entries when the log exceeds the requested cap", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(5000, "head"), true, 9000))
.mockResolvedValueOnce(page(makeEntries(5000, "tail-a"), true, 9000))
.mockResolvedValueOnce(page(makeEntries(1000, "tail-b"), false, 9000));
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 6000 },
);
expect(result.complete).toBe(true);
expect(result.truncatedHeadCount).toBe(3000);
expect(result.entries).toHaveLength(6000);
expect(
(result.entries[0] as { notification: { method: string } }).notification
.method,
).toBe("tail-a-0");
expect(fetch).toHaveBeenCalledTimes(3);
expect(requestedParams(fetch.mock.calls[1][0])).toEqual({
limit: "5000",
offset: "3000",
});
expect(requestedParams(fetch.mock.calls[2][0])).toEqual({
limit: "1000",
offset: "8000",
});
});
it("does not refetch when the matching count equals the cap", async () => {
const fetch = vi
.fn()
.mockResolvedValue(page(makeEntries(5000, "a"), false, 5000));
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 5000 },
);
expect(result.complete).toBe(true);
expect(result.truncatedHeadCount).toBe(0);
expect(fetch).toHaveBeenCalledTimes(1);
});
it("retries a rejected page fetch once and keeps paginating", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(50, "a"), true))
.mockRejectedValueOnce(new Error("socket hang up"))
.mockResolvedValueOnce(page(makeEntries(10, "b"), false));
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 100000 },
);
expect(result.complete).toBe(true);
expect(result.entries).toHaveLength(60);
expect(fetch).toHaveBeenCalledTimes(3);
expect(
(fetch.mock.calls[0][0] as { overrides: { signal: unknown } }).overrides
.signal,
).toBeInstanceOf(AbortSignal);
});
it("reports a null matching count when the header is absent", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => makeEntries(10, "a"),
headers: new Headers({ "X-Has-More": "true" }),
});
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsPage("task-1", "run-1", {
limit: 10,
});
expect(result.matchingCount).toBeNull();
expect(result.hasMore).toBe(true);
});
it("does not retry a definite client error", async () => {
const fetch = vi.fn().mockRejectedValue(new ApiRequestError(404, "{}"));
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 100000 },
);
expect(result.complete).toBe(false);
expect(fetch).toHaveBeenCalledTimes(1);
});
it("gives up after a second rejection on the same page", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(50, "a"), true))
.mockRejectedValue(new Error("socket hang up"));
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 100000 },
);
expect(result.complete).toBe(false);
expect(result.entries).toHaveLength(50);
expect(fetch).toHaveBeenCalledTimes(3);
});
it("retries a page whose body read fails", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce({
ok: true,
json: async () => {
throw new Error("terminated");
},
headers: new Headers({ "X-Has-More": "true" }),
})
.mockResolvedValueOnce(page(makeEntries(10, "a"), false));
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 100000 },
);
expect(result.complete).toBe(true);
expect(result.entries).toHaveLength(10);
expect(fetch).toHaveBeenCalledTimes(2);
});
it("aborts a page whose body stalls after the headers arrive", async () => {
vi.useFakeTimers();
try {
const fetch = vi
.fn()
.mockImplementation((call: { overrides: { signal: AbortSignal } }) =>
Promise.resolve({
ok: true,
json: () =>
new Promise((_resolve, reject) => {
call.overrides.signal.addEventListener("abort", () =>
reject(call.overrides.signal.reason),
);
}),
headers: new Headers({ "X-Has-More": "false" }),
}),
);
const client = makeClient(fetch);
const pending = client.getTaskRunSessionLogsResult("task-1", "run-1", {
limit: 100000,
});
// Once for the first attempt, once for its retry.
await vi.advanceTimersByTimeAsync(SESSION_LOGS_PAGE_TIMEOUT_MS);
await vi.advanceTimersByTimeAsync(SESSION_LOGS_PAGE_TIMEOUT_MS);
const result = await pending;
expect(result.complete).toBe(false);
expect(result.entries).toHaveLength(0);
expect(fetch).toHaveBeenCalledTimes(2);
} finally {
vi.useRealTimers();
}
});
it("marks entries collected before a failed page as incomplete", async () => {
const fetch = vi
.fn()
.mockResolvedValueOnce(page(makeEntries(50, "a"), true))
.mockResolvedValueOnce({
ok: false,
status: 500,
statusText: "Internal Server Error",
headers: new Headers(),
});
const client = makeClient(fetch);
const result = await client.getTaskRunSessionLogsResult(
"task-1",
"run-1",
{ limit: 100000 },
);
expect(result).toEqual({
entries: expect.any(Array),
complete: false,
truncatedHeadCount: 0,
});
expect(result.entries).toHaveLength(50);
expect(fetch).toHaveBeenCalledTimes(2);
});
it("treats a missing X-Has-More header as the final page", async () => {
const fetch = vi.fn().mockResolvedValue({
ok: true,
json: async () => makeEntries(10, "a"),
headers: new Headers(),
});
const client = makeClient(fetch);
const result = (
await client.getTaskRunSessionLogsResult("task-1", "run-1", {
limit: 100000,
})
).entries;
expect(result).toHaveLength(10);
expect(fetch).toHaveBeenCalledTimes(1);
});
it("stops on an empty page even if the server claims more", async () => {
const fetch = vi.fn().mockResolvedValue(page([], true));
const client = makeClient(fetch);
const result = (
await client.getTaskRunSessionLogsResult("task-1", "run-1", {
limit: 100000,
})
).entries;
expect(result).toHaveLength(0);
expect(fetch).toHaveBeenCalledTimes(1);
});
});
describe("getMcpServerIconUrl", () => {
function makeClient(fetch: ReturnType<typeof vi.fn>) {
const client = new PostHogAPIClient(
"http://localhost:8000",
async () => "token",
async () => "token",
123,
);
(
client as unknown as {
api: { baseUrl: string; fetcher: { fetch: typeof fetch } };
}
).api = { baseUrl: "http://localhost:8000", fetcher: { fetch } };
return client;
}
it("requests the icon proxy and returns an object URL for the bytes", async () => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(new Blob(["png"], { type: "image/png" })),
);
const client = makeClient(fetch);
const url = await client.getMcpServerIconUrl("linear.app", "dark");
expect(url).toMatch(/^blob:/);
expect(fetch.mock.calls[0][0].url.toString()).toBe(
"http://localhost:8000/api/environments/123/mcp_servers/icon/?domain=linear.app&theme=dark",
);
});
it("omits the theme param when none is given", async () => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(new Blob(["png"], { type: "image/png" })),
);
const client = makeClient(fetch);
await client.getMcpServerIconUrl("linear.app");
expect(fetch.mock.calls[0][0].url.toString()).toBe(
"http://localhost:8000/api/environments/123/mcp_servers/icon/?domain=linear.app",
);
});
it("treats the proxy's 404 as a definitive no-icon null, not a failure", async () => {
const fetch = vi.fn().mockRejectedValue(new ApiRequestError(404, "{}"));
const client = makeClient(fetch);
await expect(
client.getMcpServerIconUrl("no-logo.example"),
).resolves.toBeNull();
});
it("propagates non-404 failures so callers can retry", async () => {
const fetch = vi.fn().mockRejectedValue(new ApiRequestError(500, "{}"));
const client = makeClient(fetch);
await expect(client.getMcpServerIconUrl("linear.app")).rejects.toThrow(
"Failed request: [500]",
);
});
});
});
describe("manual scout run refusals", () => {
it.each([403, 409, 429])(
"preserves HTTP status %s from the production fetcher",
async (status) => {
const fetch = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ detail: "Run request refused." }), {
status,
headers: { "Content-Type": "application/json" },
}),
);
const client = new PostHogAPIClient(
"https://example.com",
async () => "test-token",
async () => "test-token",
42,
{ fetch },
);
const error = await client
.runScoutNow(42, "config-1")
.catch((value: unknown) => value);
expect(error).toBeInstanceOf(ScoutRequestError);
expect(error).toMatchObject({ status });
},
);
});
describe("report read sync", () => {
it("batches simultaneous report reads and resolves duplicate callers", async () => {
const fetch = vi
.fn()
.mockResolvedValue(
new Response(
JSON.stringify({ states: { first: true, second: false } }),
{ headers: { "Content-Type": "application/json" } },
),
);
const client = new PostHogAPIClient(
"https://example.com",
async () => "test-token",
async () => "test-token",
1,
{ fetch },
);
expect(
await Promise.all([
client.getReportReadState("first"),
client.getReportReadState("second"),
client.getReportReadState("first"),
]),
).toEqual([true, false, true]);
expect(fetch).toHaveBeenCalledOnce();
expect(JSON.parse(fetch.mock.calls[0][1].body)).toEqual({
report_ids: ["first", "second"],
});
});
it("rejects every waiting caller when read sync fails", async () => {
const fetch = vi
.fn()
.mockResolvedValue(new Response("Unavailable", { status: 503 }));
const client = new PostHogAPIClient(
"https://example.com",
async () => "test-token",
async () => "test-token",
1,
{ fetch },
);
const outcomes = await Promise.allSettled([
client.getReportReadState("first"),
client.getReportReadState("second"),
]);
expect(outcomes.map((outcome) => outcome.status)).toEqual([
"rejected",
"rejected",
]);
});
});