ad2app-lib 1.50.0 → 1.59.0

package/src/types/dealroom-wave3.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Spec 148 wave 3 (T068/T069 US8, T067 US6, T041 US9): the wire shapes the
+ * delegation, the offer-deal publication and the calendar read. Validated
+ * through class-validator, the way the backend's global ValidationPipe reads
+ * them (an empty construct, then the body's properties assigned).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { ACTING_FOR_HEADER, UpdateGrantScopesDto } from "./agency";
+import { DEALROOM_CALENDAR_KINDS, DealroomCalendarQueryDto } from "./dealroom";
+
+const errorsOf = async (dto: object): Promise<string[]> => {
+  const { validate } = await import("class-validator");
+  return (await validate(dto)).map((e) => e.property).sort();
+};
+
+/** What the ValidationPipe does: `new Dto()`, then the body's own keys. */
+const piped = (body: Record<string, unknown>) => Object.assign(new UpdateGrantScopesDto(), body);
+
+test("the data-access screen's reads-only save is unchanged and never names deals", async () => {
+  assert.deepEqual(await errorsOf(piped({ scopes: ["analytics"] })), []);
+  assert.equal(piped({ scopes: ["analytics"] }).deals, undefined);
+  assert.deepEqual(await errorsOf(piped({ scopes: [] })), ["scopes"]);
+  assert.deepEqual(await errorsOf(piped({})), ["scopes"]);
+});
+
+test("`deals` is never a read scope: it cannot ride in `scopes`", async () => {
+  assert.deepEqual(await errorsOf(piped({ scopes: ["analytics", "deals"] })), ["scopes"]);
+});
+
+test("delegation is its own boolean, with or without the reads", async () => {
+  assert.deepEqual(await errorsOf(piped({ deals: true })), []);
+  assert.deepEqual(await errorsOf(piped({ deals: false })), []);
+  assert.deepEqual(await errorsOf(piped({ scopes: ["posts"], deals: true })), []);
+  assert.deepEqual(await errorsOf(piped({ deals: "yes" })), ["deals"]);
+  assert.deepEqual(await errorsOf(piped({ scopes: [], deals: true })), ["scopes"]);
+});
+
+test("the delegate names the creator in one header, lower-case as Node reads it", () => {
+  assert.equal(ACTING_FOR_HEADER, "x-acting-for");
+});
+
+test("the calendar window needs both ends as dates", async () => {
+  assert.deepEqual(await errorsOf(new DealroomCalendarQueryDto({ from: "2026-10-01", to: "2026-11-01" })), []);
+  assert.deepEqual(await errorsOf(new DealroomCalendarQueryDto({ from: "soon" })), ["from", "to"]);
+});
+
+test("the calendar's marker kinds, in order", () => {
+  assert.deepEqual([...DEALROOM_CALENDAR_KINDS], [
+    "milestone",
+    "application_deadline",
+    "materials_due",
+    "publication_due",
+    "publish_at",
+    "bonus_ends",
+    "keep_up_ends",
+  ]);
+});
+
+test("wave 3b: the delegate-consent code, the roster's act-for flag and the followers gap's platform", async () => {
+  const { DEALROOM_CODES } = await import("./dealroom");
+  assert.equal(DEALROOM_CODES.DELEGATE_CONSENT_FORBIDDEN, "dealroom-delegate-consent-forbidden");
+  const gap: import("./dealroom").I_NearMatchGap = { kind: "followers", platform: "tiktok", followers: 8_800, band: { min: 10_000 }, percent: 12, direction: "under" };
+  assert.equal(gap.kind === "followers" && gap.platform, "tiktok");
+  const row: import("./agency").I_AgencyRosterRow = { grantId: "g", creator: { id: "c", handle: "@a" }, platforms: [], state: "active", grantedScopes: ["analytics"], canActForCreator: true };
+  assert.equal(row.canActForCreator, true);
+});

package/src/types/dealroom-wave4.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Spec 148 wave 4 (US5 T029/T030, US6 T032/T033, US7 T036/T037), DORMANT:
+ * the wire shapes of the contract step, the deal money and the payouts.
+ * Validated through class-validator, the way the backend's global
+ * ValidationPipe reads them (an empty construct, then the body's keys).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { AGENCY_CAMPAIGN_EVENT_KINDS } from "./agency-campaigns";
+import {
+  CreateDealContractDto,
+  DEAL_CONTRACT_SOURCES,
+  DEAL_CONTRACT_STATES,
+  DEAL_MONEY_ACTIONS,
+  DEAL_PAYMENT_METHODS,
+  DEAL_SIGNATURE_LEVELS,
+  DEALROOM_CODES,
+  DEALROOM_MONEY_EVENT_KINDS,
+  PAYOUT_PROFILE_FIELDS,
+  StartDealPaymentDto,
+  UpsertPayoutProfileDto,
+} from "./dealroom";
+
+const errorsOf = async (dto: object): Promise<string[]> => {
+  const { validate } = await import("class-validator");
+  return (await validate(dto)).map((e) => e.property).sort();
+};
+
+test("the contract step's vocabulary (data-model §dealroom_contracts)", () => {
+  assert.deepEqual([...DEAL_CONTRACT_SOURCES], ["template", "uploaded"]);
+  assert.deepEqual([...DEAL_CONTRACT_STATES], ["draft", "sent", "signed"]);
+  assert.deepEqual([...DEAL_SIGNATURE_LEVELS], ["SES", "QES"]);
+});
+
+test("a template contract takes the form fields; an upload takes the file", async () => {
+  const template = Object.assign(new CreateDealContractDto(), {
+    source: "template",
+    deliverables: ["1 reel on Instagram"],
+    liveByAt: "2026-11-01T10:00:00.000Z",
+    licenceMonths: 6,
+  });
+  assert.deepEqual(await errorsOf(template), []);
+
+  const upload = Object.assign(new CreateDealContractDto(), { source: "uploaded", fileName: "umowa.pdf", fileBase64: "JVBERi0=" });
+  assert.deepEqual(await errorsOf(upload), []);
+
+  assert.deepEqual(await errorsOf(Object.assign(new CreateDealContractDto(), { source: "fax" })), ["source"]);
+  assert.deepEqual(await errorsOf(Object.assign(new CreateDealContractDto(), { source: "template", signatureLevel: "AES" })), ["signatureLevel"]);
+  assert.deepEqual(await errorsOf(Object.assign(new CreateDealContractDto(), { source: "template", licenceMonths: -1 })), ["licenceMonths"]);
+});
+
+test("a payment names its method or none (card by default; invoice for big sums)", async () => {
+  assert.deepEqual([...DEAL_PAYMENT_METHODS], ["card", "invoice"]);
+  assert.deepEqual(await errorsOf(new StartDealPaymentDto()), []);
+  assert.deepEqual(await errorsOf(Object.assign(new StartDealPaymentDto(), { method: "invoice" })), []);
+  assert.deepEqual(await errorsOf(Object.assign(new StartDealPaymentDto(), { method: "cash" })), ["method"]);
+});
+
+test("the payout profile: IBAN and payout currency, nothing about a provider", async () => {
+  const ok = Object.assign(new UpsertPayoutProfileDto(), { iban: "PL61109010140000071219812874", payoutCurrency: "PLN", nip: "5260250274" });
+  assert.deepEqual(await errorsOf(ok), []);
+  assert.deepEqual(await errorsOf(Object.assign(new UpsertPayoutProfileDto(), { iban: "not an iban", payoutCurrency: "PLN" })), ["iban"]);
+  assert.deepEqual(await errorsOf(Object.assign(new UpsertPayoutProfileDto(), { iban: "PL61109010140000071219812874", payoutCurrency: "zł" })), ["payoutCurrency"]);
+  assert.equal("stripeAccountId" in ok, false);
+  assert.deepEqual([...PAYOUT_PROFILE_FIELDS], ["settlement_form", "nip", "tax_statement", "intl_billing_data", "iban", "payout_currency"]);
+});
+
+test("the money acts a deal view offers its reader", () => {
+  assert.deepEqual([...DEAL_MONEY_ACTIONS], ["send_contract", "pay_deposit", "decline_deposit", "fund", "refund", "claim_guarantee"]);
+});
+
+test("the four wave-4 codes are added, never renamed", () => {
+  assert.equal(DEALROOM_CODES.DEAL_BELOW_MINIMUM, "dealroom-deal-below-minimum");
+  assert.equal(DEALROOM_CODES.MONEY_WRONG_STEP, "dealroom-money-wrong-step");
+  assert.equal(DEALROOM_CODES.CONTRACT_EXISTS, "dealroom-contract-exists");
+  assert.equal(DEALROOM_CODES.GUARANTEE_UNAVAILABLE, "dealroom-guarantee-unavailable");
+});
+
+test("contract, money and payout steps are kinds in 175's one event log (FR-008a)", () => {
+  for (const kind of DEALROOM_MONEY_EVENT_KINDS) {
+    assert.ok((AGENCY_CAMPAIGN_EVENT_KINDS as readonly string[]).includes(kind), kind);
+    assert.ok(kind.length <= 32, kind);
+  }
+  assert.deepEqual([...DEALROOM_MONEY_EVENT_KINDS], [
+    "contract_sent",
+    "contract_signed",
+    "contract_declined",
+    "deposit_paid",
+    "deal_funded",
+    "deal_closed_unviewed",
+    "deal_refund_requested",
+    "deal_refunded",
+    "guarantee_claimed",
+    "payout_initiated",
+    "payout_paid",
+  ]);
+});
+
+test("a payout profile with no payable settlement form names no billing variant", () => {
+  const profile: import("./dealroom").I_PayoutProfile = { billingVariant: null, track: null, payoutCurrency: "PLN", kycState: "none" };
+  assert.equal(profile.billingVariant, null);
+});

package/src/types/dealroom.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Spec 148 (Dealroom), T060: the additive types on top of 175's agency files.
+ *
+ * Two kinds of pin live here. The ADDITIONS (brand type, the `deals`
+ * delegation scope, application origins, the `apply` act, the Dealroom codes
+ * and the dormant money states) and the NON-CHANGES that make them safe: 175's
+ * offer status list and the scope set an organization may ask for stay
+ * byte-identical to 1.50.0.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  AGENCY_GRANT_SCOPES,
+  AGENCY_ORGANIZATION_TYPES,
+  CREATOR_ACCESS_GRANT_ORIGINS,
+  DELEGATION_SCOPES,
+  isAgencyGrantScope,
+  isGrantScope,
+} from "./agency";
+import {
+  AGENCY_CAMPAIGN_MEMBER_ORIGINS,
+  AGENCY_OFFER_ACTIONS,
+  AGENCY_OFFER_STATUSES,
+  CampaignOfferActDto,
+} from "./agency-campaigns";
+import { I_OfferStatus } from "./I_Offer";
+import {
+  CAMPAIGN_VISIBILITIES,
+  COMMISSION_AD_SPACE_DECISIONS,
+  COMMISSION_AD_SPACE_STATES,
+  COMMISSION_JOIN_STATES,
+  COMMISSION_LINK_MODES,
+  COMMISSION_LINK_STATES,
+  COMMISSION_MATERIAL_KINDS,
+  COMMISSION_NETWORKS,
+  ReviewCommissionAdSpaceDto,
+  COMMISSION_OFFER_STATES,
+  DEALROOM_CODES,
+  DEALROOM_PROFILE_FIELDS,
+  DEAL_MONEY_STATES,
+  DEAL_PAYOUT_STATES,
+  PAYOUT_BILLING_VARIANTS,
+  PAYOUT_LEDGER_SOURCES,
+  PAYOUT_LEDGER_STATES,
+  isCampaignVisibility,
+} from "./dealroom";
+import * as typesIndex from "./index";
+import { EVENTS } from "../analytics";
+
+// ── Non-changes (the 175 contract stays intact) ─────────────────────────────
+
+test("AGENCY_OFFER_STATUSES is byte-identical to 1.50.0: no offer status is added or remodeled", () => {
+  assert.deepEqual(
+    [...AGENCY_OFFER_STATUSES],
+    [
+      I_OfferStatus.SENT,
+      I_OfferStatus.INFLUENCER_NEGOTIATED,
+      I_OfferStatus.AGENCY_NEGOTIATED,
+      I_OfferStatus.ACCEPTED,
+      I_OfferStatus.CONFIRMED,
+      I_OfferStatus.REJECTED,
+      I_OfferStatus.WITHDRAWN,
+    ],
+  );
+  assert.deepEqual(
+    Object.entries(I_OfferStatus),
+    [
+      ["DRAFT", "draft"],
+      ["SENT", "sent"],
+      ["DELETED", "deleted"],
+      ["ACCEPTED", "accepted"],
+      ["REJECTED", "rejected"],
+      ["INFLUENCER_NEGOTIATED", "influencerNegotiated"],
+      ["AGENCY_NEGOTIATED", "agencyNegotiated"],
+      ["CONFIRMED", "confirmed"],
+      ["ALTERNATIVE_SUGGESTED", "alternativeSuggested"],
+      ["WITHDRAWN", "withdrawn"],
+    ],
+  );
+});
+
+test("AGENCY_GRANT_SCOPES (what an organization may ask for) is unchanged and never carries `deals`", () => {
+  assert.deepEqual([...AGENCY_GRANT_SCOPES], ["analytics", "comments", "posts"]);
+  assert.equal(isAgencyGrantScope("deals"), false);
+});
+
+// ── Additions in 175's files ────────────────────────────────────────────────
+
+test("an organization is an agency or a brand", () => {
+  assert.deepEqual([...AGENCY_ORGANIZATION_TYPES], ["agency", "brand"]);
+});
+
+test("a grant may originate from a Dealroom application", () => {
+  assert.deepEqual([...CREATOR_ACCESS_GRANT_ORIGINS], ["invite_link", "agency_request", "dealroom_application"]);
+});
+
+test("delegation is one creator-only scope, `deals`, kept out of the organization's ask", () => {
+  assert.deepEqual([...DELEGATION_SCOPES], ["deals"]);
+  for (const scope of [...AGENCY_GRANT_SCOPES, ...DELEGATION_SCOPES]) assert.equal(isGrantScope(scope), true);
+  for (const notAScope of ["publish", "payouts", "contract", "settings", "", "Deals"]) {
+    assert.equal(isGrantScope(notAScope), false, `must refuse: ${notAScope}`);
+  }
+});
+
+test("a campaign membership comes from an invitation or an application", () => {
+  assert.deepEqual([...AGENCY_CAMPAIGN_MEMBER_ORIGINS], ["invitation", "application"]);
+});
+
+test("`apply` is an offer act, appended after 175's four", () => {
+  assert.deepEqual([...AGENCY_OFFER_ACTIONS], ["accept", "counter", "confirm", "reject", "apply"]);
+  assert.equal(new CampaignOfferActDto({ action: "apply" }).action, "apply");
+});
+
+// ── dealroom.ts ─────────────────────────────────────────────────────────────
+
+test("a campaign is private (every 175 campaign today) or open (listed in the feed)", () => {
+  assert.deepEqual([...CAMPAIGN_VISIBILITIES], ["private", "open"]);
+  assert.equal(isCampaignVisibility("open"), true);
+  assert.equal(isCampaignVisibility("public"), false);
+});
+
+test("the incomplete-profile state names the two fields that can be missing", () => {
+  assert.deepEqual([...DEALROOM_PROFILE_FIELDS], ["country", "niches"]);
+});
+
+test("DEALROOM_CODES are exactly the contract's thirteen, wave 4's four, the commission lane's four and review 148's three", () => {
+  assert.deepEqual(Object.values(DEALROOM_CODES).sort(), [
+    "commission-ad-space-decision-closed",
+    "commission-ad-space-pending",
+    "commission-ad-space-unavailable",
+    "commission-network-unavailable",
+    "dealroom-brand-door-closed",
+    "dealroom-brand-no-roster",
+    "dealroom-config-missing",
+    "dealroom-contract-exists",
+    "dealroom-contract-unsigned",
+    "dealroom-deal-below-minimum",
+    "dealroom-delegate-consent-forbidden",
+    "dealroom-delegate-forbidden",
+    "dealroom-delegate-own-deal",
+    "dealroom-deposit-required",
+    "dealroom-guarantee-unavailable",
+    "dealroom-listing-frozen",
+    "dealroom-logo-required",
+    "dealroom-money-disabled",
+    "dealroom-money-wrong-step",
+    "dealroom-near-match-not-appliable",
+    "dealroom-not-funded",
+    "dealroom-offer-filled",
+    "dealroom-profile-incomplete",
+    "dealroom-template-pending",
+  ]);
+});
+
+test("the deal money states mirror data-model's state machine exactly; payout is its own column", () => {
+  assert.deepEqual(
+    [...DEAL_MONEY_STATES],
+    [
+      "awaiting_material",
+      "material_submitted",
+      "deposit_paid",
+      "funded",
+      "approved",
+      "published",
+      "closed_unviewed",
+      "refund_pending",
+      "refunded",
+      "guarantee_claimed",
+    ],
+  );
+  assert.deepEqual([...DEAL_PAYOUT_STATES], ["none", "initiated", "paid"]);
+});
+
+test("payout profiles and the ledger carry the data-model's values", () => {
+  assert.deepEqual([...PAYOUT_BILLING_VARIANTS], ["faktura_vat", "umowa_o_dzielo", "international"]);
+  assert.deepEqual([...PAYOUT_LEDGER_SOURCES], ["deal", "pot", "commission"]);
+  assert.deepEqual([...PAYOUT_LEDGER_STATES], ["earned", "validated", "paid"]);
+});
+
+test("the commission lane carries the two networks and its own states", () => {
+  assert.deepEqual([...COMMISSION_NETWORKS], ["awin", "admitad"]);
+  assert.deepEqual([...COMMISSION_OFFER_STATES], ["live", "paused", "gone"]);
+  assert.deepEqual([...COMMISSION_LINK_STATES], ["active", "suspended"]);
+  assert.deepEqual([...COMMISSION_LINK_MODES], ["subnetwork", "deeplink"]);
+});
+
+// ── Commission lane, amended 2026-10-07 (Admitad Ad Space, Awin consent) ────
+
+test("an Admitad Ad Space is reviewed, registered, rejected or suspended, never anything else", () => {
+  assert.deepEqual([...COMMISSION_AD_SPACE_STATES], ["pending_review", "registered", "rejected", "suspended"]);
+  assert.deepEqual([...COMMISSION_AD_SPACE_DECISIONS], ["approve", "reject", "suspend"]);
+});
+
+test("a join answers a link, a deep link, or an Ad Space under review", () => {
+  assert.deepEqual([...COMMISSION_JOIN_STATES], ["link", "deeplink", "ad_space_pending"]);
+});
+
+test("advertiser materials have named kinds", () => {
+  assert.deepEqual([...COMMISSION_MATERIAL_KINDS], ["logo", "banner", "landing_preview", "coupon"]);
+});
+
+test("ReviewCommissionAdSpaceDto carries the admin's decision", () => {
+  assert.equal(new ReviewCommissionAdSpaceDto({ decision: "approve" }).decision, "approve");
+  assert.equal(new ReviewCommissionAdSpaceDto().decision, undefined);
+});
+
+test("dealroom.ts is exported from the types index", () => {
+  assert.equal((typesIndex as Record<string, unknown>).DEALROOM_CODES, DEALROOM_CODES);
+});
+
+// ── Analytics: Dealroom-only events ─────────────────────────────────────────
+
+test("Dealroom adds only the events 175 has none for", () => {
+  const dealroom = Object.entries(EVENTS)
+    .filter(([key]) => key.startsWith("DEALROOM_"))
+    .map(([, value]) => value)
+    .sort();
+  assert.deepEqual(dealroom, [
+    "dealroom_applied",
+    "dealroom_broaden_toggled",
+    "dealroom_connect_from_near_match_clicked",
+    "dealroom_deal_money_state_changed",
+    "dealroom_deal_payout_state_changed",
+    "dealroom_delegation_changed",
+    "dealroom_feed_viewed",
+    "dealroom_listing_opened",
+    "dealroom_near_match_promoted",
+    "dealroom_near_match_shown",
+  ]);
+});