ad2app-lib 1.47.0 → 1.49.0

package/src/analytics/index.ts

@@ -191,6 +191,23 @@ export const EVENTS = {
   // creators an agency went looking for.
   AGENCY_DISCOVER_SEARCHED: 'agency_discover_searched',
   AGENCY_ACCESS_REQUESTED: 'agency_access_requested',
+  // The campaign loop (175 US7). Server-owned: each is captured in the act's
+  // own transaction path, under the ACTOR's distinct id.
+  AGENCY_CAMPAIGN_CREATED: 'agency_campaign_created',
+  AGENCY_CAMPAIGN_CREATOR_INVITED: 'agency_campaign_creator_invited',
+  AGENCY_CAMPAIGN_JOINED: 'agency_campaign_joined',
+  AGENCY_CAMPAIGN_DECLINED: 'agency_campaign_declined',
+  AGENCY_CAMPAIGN_LEFT: 'agency_campaign_left',
+  AGENCY_CAMPAIGN_CREATOR_REMOVED: 'agency_campaign_creator_removed',
+  AGENCY_CAMPAIGN_OFFER_SENT: 'agency_campaign_offer_sent',
+  AGENCY_CAMPAIGN_OFFER_ACTED: 'agency_campaign_offer_acted',
+  AGENCY_CAMPAIGN_MATERIAL_UPLOADED: 'agency_campaign_material_uploaded',
+  AGENCY_CAMPAIGN_MATERIAL_REVIEWED: 'agency_campaign_material_reviewed',
+  AGENCY_CAMPAIGN_PUBLISHED: 'agency_campaign_published',
+  AGENCY_CAMPAIGN_MILESTONE_CONFIRMED: 'agency_campaign_milestone_confirmed',
+  // Threads (175 US8). Never the message body: a conversation is not analytics.
+  AGENCY_THREAD_STARTED: 'agency_thread_started',
+  AGENCY_THREAD_MESSAGE_SENT: 'agency_thread_message_sent',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -427,6 +444,11 @@ export interface AgencyEventProperties {
   creator_user_id?: string;
 }
 
+/** A campaign-loop event: the agency event plus the campaign it concerns. */
+export interface AgencyCampaignEventProperties extends AgencyEventProperties {
+  campaign_id: string;
+}
+
 export interface EventProperties {
   [EVENTS.LANDING_CTA_CLICKED]: {
     location:
@@ -675,6 +697,23 @@ export interface EventProperties {
   // `matched` only. The query itself is never sent (FR-015).
   [EVENTS.AGENCY_DISCOVER_SEARCHED]: AgencyEventProperties & { matched: boolean };
   [EVENTS.AGENCY_ACCESS_REQUESTED]: AgencyEventProperties;
+  // The campaign loop (175 US7): which campaign, and for an act, which one.
+  // Never a price: an amount in analytics is a creator's rate in a dashboard.
+  [EVENTS.AGENCY_CAMPAIGN_CREATED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_CREATOR_INVITED]: AgencyCampaignEventProperties & { with_access_request: boolean };
+  [EVENTS.AGENCY_CAMPAIGN_JOINED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_DECLINED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_LEFT]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_CREATOR_REMOVED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_OFFER_SENT]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_OFFER_ACTED]: AgencyCampaignEventProperties & { action: 'accept' | 'counter' | 'confirm' | 'reject' };
+  [EVENTS.AGENCY_CAMPAIGN_MATERIAL_UPLOADED]: AgencyCampaignEventProperties & { version: number };
+  [EVENTS.AGENCY_CAMPAIGN_MATERIAL_REVIEWED]: AgencyCampaignEventProperties & { action: 'approve' | 'request_changes' | 'reject' };
+  [EVENTS.AGENCY_CAMPAIGN_PUBLISHED]: AgencyCampaignEventProperties;
+  [EVENTS.AGENCY_CAMPAIGN_MILESTONE_CONFIRMED]: AgencyCampaignEventProperties;
+  // Threads (175 US8): which thread, never its content.
+  [EVENTS.AGENCY_THREAD_STARTED]: AgencyEventProperties & { thread_id: string };
+  [EVENTS.AGENCY_THREAD_MESSAGE_SENT]: AgencyEventProperties & { thread_id: string };
 }
 
 /** Canonical person property keys (set via identify / $set). */

package/src/types/I_Offer.ts

@@ -41,6 +41,8 @@ export enum I_OfferStatus {
   AGENCY_NEGOTIATED = 'agencyNegotiated',
   CONFIRMED = 'confirmed',
   ALTERNATIVE_SUGGESTED = 'alternativeSuggested',
+  /** The creator left the campaign before the offer was confirmed (spec 175 US7). Added, never renamed: Postgres enums only grow. */
+  WITHDRAWN = 'withdrawn',
 }
 
 export declare class I_OfferGetDTO {

package/src/types/agency-campaigns.test.ts

@@ -0,0 +1,85 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  AGENCY_CAMPAIGN_STEPS,
+  AGENCY_OFFER_STATUSES,
+  CAMPAIGN_PLACEMENTS,
+  CampaignOfferActDto,
+  CreateAgencyCampaignDto,
+  SETTLEMENT_FORMS,
+  isCampaignPlacement,
+} from "./agency-campaigns";
+import { I_OfferStatus } from "./I_Offer";
+
+test("the placements list is exactly FR-025's, one list per platform", () => {
+  assert.deepEqual(CAMPAIGN_PLACEMENTS, {
+    instagram: ["reel", "post", "carousel", "stories", "collab_post"],
+    tiktok: ["video", "repost", "duet", "stories"],
+    youtube: ["video", "short", "integration", "community_post"],
+    facebook: ["post", "reel", "stories"],
+    linkedin: ["post", "article"],
+  });
+});
+
+test("isCampaignPlacement checks the PAIR, and fails closed", () => {
+  assert.equal(isCampaignPlacement("instagram", "reel"), true);
+  assert.equal(isCampaignPlacement("youtube", "short"), true);
+  // A real placement on the wrong platform is not a placement.
+  assert.equal(isCampaignPlacement("linkedin", "reel"), false);
+  assert.equal(isCampaignPlacement("twitter", "post"), false);
+  // Prototype keys are not platforms.
+  assert.equal(isCampaignPlacement("constructor", "post"), false);
+  assert.equal(isCampaignPlacement("__proto__", "post"), false);
+});
+
+test("withdrawn is ADDED to the offer enum and the agency loop never writes the legacy-only values", () => {
+  assert.equal(I_OfferStatus.WITHDRAWN, "withdrawn");
+  for (const legacyOnly of [I_OfferStatus.DRAFT, I_OfferStatus.DELETED, I_OfferStatus.ALTERNATIVE_SUGGESTED]) {
+    assert.equal((AGENCY_OFFER_STATUSES as readonly string[]).includes(legacyOnly), false);
+  }
+});
+
+test("the board has FR-024's columns in loop order", () => {
+  assert.deepEqual(
+    [...AGENCY_CAMPAIGN_STEPS],
+    ["invited", "joined", "offer_sent", "negotiating", "confirmed", "material_in", "approved", "published"],
+  );
+});
+
+test("the settlement forms are the creator's three (FR-027)", () => {
+  assert.deepEqual([...SETTLEMENT_FORMS], ["invoice", "contract", "barter"]);
+});
+
+test("DTOs construct with no arguments, as the validation pipe does", () => {
+  assert.doesNotThrow(() => new CreateAgencyCampaignDto());
+  assert.doesNotThrow(() => new CampaignOfferActDto());
+  assert.equal(new CreateAgencyCampaignDto({ name: "Spring", text: "Concept" }).text, "Concept");
+});
+
+test("a material is a raster image or a video: SVG and HTML are refused (review L5)", async () => {
+  const { validate } = await import("class-validator");
+  const { PrepareMaterialUploadDto } = await import("./agency-campaigns");
+  const check = async (contentType: string) =>
+    (await validate(new PrepareMaterialUploadDto({ fileName: "f", contentType, sizeBytes: 1 }))).length === 0;
+  assert.equal(await check("video/mp4"), true);
+  assert.equal(await check("image/jpeg"), true);
+  assert.equal(await check("image/svg+xml"), false);
+  assert.equal(await check("text/html"), false);
+});
+
+test("thread messages are bounded and never empty (US8)", async () => {
+  const { validate } = await import("class-validator");
+  const { PostThreadMessageDto, THREAD_MESSAGE_MAX, AGENCY_THREAD_CODES } = await import("./agency-threads");
+  assert.equal((await validate(new PostThreadMessageDto({ text: "hi" }))).length, 0);
+  assert.notEqual((await validate(new PostThreadMessageDto({ text: "" }))).length, 0);
+  assert.notEqual((await validate(new PostThreadMessageDto({ text: "x".repeat(THREAD_MESSAGE_MAX + 1) }))).length, 0);
+  assert.equal(AGENCY_THREAD_CODES.CLOSED, "agency-thread-closed");
+});
+
+test("the picker's photo list and the API's rule are one rule (epic verify E7)", async () => {
+  const { MATERIAL_CONTENT_TYPE, MATERIAL_IMAGE_TYPES } = await import("./agency-campaigns");
+  for (const type of MATERIAL_IMAGE_TYPES) assert.equal(MATERIAL_CONTENT_TYPE.test(type), true, type);
+  for (const type of ["image/svg+xml", "text/plain", "image/pngx", "application/octet-stream", ""]) assert.equal(MATERIAL_CONTENT_TYPE.test(type), false, type);
+  assert.equal(MATERIAL_CONTENT_TYPE.test("video/quicktime"), true);
+});