Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions .github/issue-evidence/11597-audience-segments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Issue #11597: Cloud advertising audience segments

Branch: `feat/11597-audience-segments`

## Implemented

- Added `ad_audience_segments` storage with organization scoping, creator attribution, server-owned targeting JSON, metadata, timestamps, and migration `0166_ad_audience_segments.sql`.
- Added advertising service APIs for list/get/create/update/delete/apply audience segments.
- Added REST routes:
- `GET|POST /api/v1/advertising/audience-segments`
- `GET|PATCH|DELETE /api/v1/advertising/audience-segments/:id`
- `POST /api/v1/advertising/audience-segments/:id/apply`
- Added `audienceSegmentId` support to campaign create/update and app promotion advertising config. Requests reject sending both raw `targeting` and `audienceSegmentId`.
- Added validation for age ranges, gender combinations, and bounded deduped targeting arrays.
- Added Meta provider mapping for saved segment targeting fields: locations, age, genders, interests, behaviors, custom audiences, excluded audiences, placements, and languages. Google/TikTok providers are unchanged because their current campaign adapters do not apply targeting payloads.
- Added a saved-segment selector to the app promotion advertising tab.

## API examples

Create segment:

```json
POST /api/v1/advertising/audience-segments
{
"name": "US product launch",
"targeting": {
"locations": ["US"],
"ageMin": 21,
"ageMax": 45,
"genders": ["all"],
"interests": ["ai agents"],
"customAudiences": ["launch-list"]
}
}
```

Apply segment:

```json
POST /api/v1/advertising/audience-segments/{segmentId}/apply
{
"campaignId": "{campaignId}"
}
```

Create campaign from segment:

```json
POST /api/v1/advertising/campaigns
{
"adAccountId": "{adAccountId}",
"name": "Launch campaign",
"objective": "traffic",
"budgetType": "daily",
"budgetAmount": 100,
"audienceSegmentId": "{segmentId}"
}
```

## Verification

- `bun install` passed in the issue worktree.
- `bun run build:core` passed.
- `bun test packages/cloud/shared/src/lib/services/__tests__/ad-audience-segments.test.ts` passed: 4 tests, 11 assertions.
- `bunx biome check --write ...` passed on touched files.
- `bun run --cwd packages/cloud/shared typecheck` passed.
- `bun run --cwd packages/cloud/api typecheck` passed.
- `bun run --cwd packages/ui typecheck` passed.
- `git diff --check` passed.
- `bun run --cwd packages/cloud/api codegen` regenerated `packages/cloud/api/src/_router.generated.ts`.

## App visual audit

`bun run --cwd packages/app audit:app` was run after the promotion dialog UI change.

Result: 348 of 349 Playwright view checks passed. The command exited 1 on the final aggregate ratchet gate for two unrelated pre-existing minimalism regressions:

- `plugin-inbox-gui @ mobile-landscape`: whitespace ratio `0.53 < baselined 0.56 - 5% tolerance (0.53)`
- `plugin-screenshare-gui @ mobile-portrait`: whitespace ratio `0.45 < baselined 0.48 - 5% tolerance (0.46)`

The touched reachable `/apps` views passed across mobile portrait, mobile landscape, desktop landscape, and iPad portrait during this run.

## N/A evidence

- Live LLM trajectory: N/A - this change does not alter prompt, model, provider, evaluator, or agent reasoning behavior.
- Live ad provider spend/campaign creation: N/A - the provider call path is covered by service tests with provider adapter stubs; no live ad account credentials or campaign spend were used in this local validation.
- Video walkthrough: N/A - the dashboard change is a selector in an existing promotion dialog; the full app audit screenshots were captured by `audit:app`, but the command failed only on unrelated views listed above.
17 changes: 16 additions & 1 deletion packages/cloud/api/src/_router.generated.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* AUTO-GENERATED by src/_generate-router.mjs - do not edit by hand.
* Re-run `bun run codegen` after adding or removing a route.ts file.
*
* 620 routes mounted, 0 skipped (still Next-shaped).
* 623 routes mounted, 0 skipped (still Next-shaped).
*/

/* eslint-disable */
Expand Down Expand Up @@ -233,6 +233,9 @@ import _route_v1_advertising_accounts_discover_route from "../v1/advertising/acc
import _route_v1_advertising_accounts_p_id_media_route from "../v1/advertising/accounts/[id]/media/route";
import _route_v1_advertising_accounts_p_id_route from "../v1/advertising/accounts/[id]/route";
import _route_v1_advertising_accounts_route from "../v1/advertising/accounts/route";
import _route_v1_advertising_audience_segments_p_id_apply_route from "../v1/advertising/audience-segments/[id]/apply/route";
import _route_v1_advertising_audience_segments_p_id_route from "../v1/advertising/audience-segments/[id]/route";
import _route_v1_advertising_audience_segments_route from "../v1/advertising/audience-segments/route";
import _route_v1_advertising_campaigns_p_id_analytics_route from "../v1/advertising/campaigns/[id]/analytics/route";
import _route_v1_advertising_campaigns_p_id_creatives_route from "../v1/advertising/campaigns/[id]/creatives/route";
import _route_v1_advertising_campaigns_p_id_dayparting_route from "../v1/advertising/campaigns/[id]/dayparting/route";
Expand Down Expand Up @@ -1198,6 +1201,18 @@ export function mountRoutes(app: Hono<AppEnv>): void {
"/api/v1/advertising/accounts",
_route_v1_advertising_accounts_route,
);
app.route(
"/api/v1/advertising/audience-segments/:id/apply",
_route_v1_advertising_audience_segments_p_id_apply_route,
);
app.route(
"/api/v1/advertising/audience-segments/:id",
_route_v1_advertising_audience_segments_p_id_route,
);
app.route(
"/api/v1/advertising/audience-segments",
_route_v1_advertising_audience_segments_route,
);
app.route(
"/api/v1/advertising/campaigns/:id/analytics",
_route_v1_advertising_campaigns_p_id_analytics_route,
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
/**
* POST /api/v1/advertising/audience-segments/[id]/apply — apply a segment to a campaign.
*/

import { Hono } from "hono";
import { failureResponse } from "@/lib/api/cloud-worker-errors";
import { requireUserOrApiKeyWithOrg } from "@/lib/auth/workers-hono-auth";
import { advertisingService } from "@/lib/services/advertising";
import { ApplyAudienceSegmentSchema } from "@/lib/services/advertising/schemas";
import { logger } from "@/lib/utils/logger";
import type { AppEnv } from "@/types/cloud-worker-env";

const app = new Hono<AppEnv>();

type CampaignRecord = NonNullable<
Awaited<ReturnType<typeof advertisingService.getCampaign>>
>;

function serializeTargeting(targeting: CampaignRecord["targeting"]) {
return {
locations: targeting.locations,
ageMin: targeting.age_min,
ageMax: targeting.age_max,
genders: targeting.genders,
interests: targeting.interests,
behaviors: targeting.behaviors,
customAudiences: targeting.custom_audiences,
excludedAudiences: targeting.excluded_audiences,
placements: targeting.placements,
languages: targeting.languages,
};
}

app.post("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
const id = c.req.param("id")!;
const body = await c.req.json();
const parsed = ApplyAudienceSegmentSchema.safeParse(body);
if (!parsed.success) {
return c.json(
{ error: "Invalid request", details: parsed.error.flatten() },
400,
);
}

const campaign = await advertisingService.applyAudienceSegmentToCampaign(
id,
parsed.data.campaignId,
user.organization_id,
);

logger.info("[Advertising API] Audience segment applied", {
segmentId: id,
campaignId: campaign.id,
});

return c.json({
id: campaign.id,
name: campaign.name,
status: campaign.status,
targeting: serializeTargeting(campaign.targeting),
updatedAt: campaign.updated_at.toISOString(),
});
} catch (error) {
return failureResponse(c, error);
}
});

export default app;
79 changes: 79 additions & 0 deletions packages/cloud/api/v1/advertising/audience-segments/[id]/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
/**
* GET /api/v1/advertising/audience-segments/[id] — get a saved segment.
* PATCH /api/v1/advertising/audience-segments/[id] — update a saved segment.
* DELETE /api/v1/advertising/audience-segments/[id] — delete a saved segment.
*/

import { Hono } from "hono";
import { failureResponse } from "@/lib/api/cloud-worker-errors";
import { requireUserOrApiKeyWithOrg } from "@/lib/auth/workers-hono-auth";
import { advertisingService } from "@/lib/services/advertising";
import { UpdateAudienceSegmentSchema } from "@/lib/services/advertising/schemas";
import { logger } from "@/lib/utils/logger";
import type { AppEnv } from "@/types/cloud-worker-env";

const app = new Hono<AppEnv>();

app.get("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
const id = c.req.param("id")!;
const segment = await advertisingService.getAudienceSegment(
id,
user.organization_id,
);
if (!segment) {
return c.json({ error: "Audience segment not found" }, 404);
}
return c.json({ segment });
} catch (error) {
return failureResponse(c, error);
}
});

app.patch("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
const id = c.req.param("id")!;
const body = await c.req.json();
const parsed = UpdateAudienceSegmentSchema.safeParse(body);
if (!parsed.success) {
return c.json(
{ error: "Invalid request", details: parsed.error.flatten() },
400,
);
}

const segment = await advertisingService.updateAudienceSegment(
id,
user.organization_id,
{
name: parsed.data.name,
description: parsed.data.description,
targeting: parsed.data.targeting,
},
);
logger.info("[Advertising API] Audience segment updated", {
segmentId: id,
});
return c.json({ segment });
} catch (error) {
return failureResponse(c, error);
}
});

app.delete("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
const id = c.req.param("id")!;
await advertisingService.deleteAudienceSegment(id, user.organization_id);
logger.info("[Advertising API] Audience segment deleted", {
segmentId: id,
});
return c.json({ success: true });
} catch (error) {
return failureResponse(c, error);
}
});

export default app;
57 changes: 57 additions & 0 deletions packages/cloud/api/v1/advertising/audience-segments/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
/**
* GET /api/v1/advertising/audience-segments — list saved segments.
* POST /api/v1/advertising/audience-segments — create a saved segment.
*/

import { Hono } from "hono";
import { failureResponse } from "@/lib/api/cloud-worker-errors";
import { requireUserOrApiKeyWithOrg } from "@/lib/auth/workers-hono-auth";
import { advertisingService } from "@/lib/services/advertising";
import { CreateAudienceSegmentSchema } from "@/lib/services/advertising/schemas";
import { logger } from "@/lib/utils/logger";
import type { AppEnv } from "@/types/cloud-worker-env";

const app = new Hono<AppEnv>();

app.get("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
const segments = await advertisingService.listAudienceSegments(
user.organization_id,
);
return c.json({ segments, count: segments.length });
} catch (error) {
return failureResponse(c, error);
}
});

app.post("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
const body = await c.req.json();
const parsed = CreateAudienceSegmentSchema.safeParse(body);
if (!parsed.success) {
return c.json(
{ error: "Invalid request", details: parsed.error.flatten() },
400,
);
}

const segment = await advertisingService.createAudienceSegment({
organizationId: user.organization_id,
userId: user.id,
name: parsed.data.name,
description: parsed.data.description,
targeting: parsed.data.targeting,
});

logger.info("[Advertising API] Audience segment created", {
segmentId: segment.id,
});
return c.json({ segment }, 201);
} catch (error) {
return failureResponse(c, error);
}
});

export default app;
23 changes: 22 additions & 1 deletion packages/cloud/api/v1/advertising/campaigns/[id]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,25 @@ import type { AppEnv } from "@/types/cloud-worker-env";

const app = new Hono<AppEnv>();

type CampaignRecord = NonNullable<
Awaited<ReturnType<typeof advertisingService.getCampaign>>
>;

function serializeTargeting(targeting: CampaignRecord["targeting"]) {
return {
locations: targeting.locations,
ageMin: targeting.age_min,
ageMax: targeting.age_max,
genders: targeting.genders,
interests: targeting.interests,
behaviors: targeting.behaviors,
customAudiences: targeting.custom_audiences,
excludedAudiences: targeting.excluded_audiences,
placements: targeting.placements,
languages: targeting.languages,
};
}

app.get("/", async (c) => {
try {
const user = await requireUserOrApiKeyWithOrg(c);
Expand Down Expand Up @@ -42,8 +61,8 @@ app.get("/", async (c) => {
creditsSpent: campaign.credits_spent,
startDate: campaign.start_date?.toISOString(),
endDate: campaign.end_date?.toISOString(),
targeting: campaign.targeting,
dayparting: campaign.metadata.dayparting ?? null,
targeting: serializeTargeting(campaign.targeting),
totalSpend: campaign.total_spend,
totalImpressions: campaign.total_impressions,
totalClicks: campaign.total_clicks,
Expand Down Expand Up @@ -89,6 +108,7 @@ app.patch("/", async (c) => {
: undefined,
targeting: parsed.data.targeting,
dayparting: parsed.data.dayparting,
audienceSegmentId: parsed.data.audienceSegmentId,
},
);

Expand All @@ -99,6 +119,7 @@ app.patch("/", async (c) => {
name: campaign.name,
status: campaign.status,
dayparting: campaign.metadata.dayparting ?? null,
targeting: serializeTargeting(campaign.targeting),
updatedAt: campaign.updated_at.toISOString(),
});
} catch (error) {
Expand Down
Loading
Loading