ad2app-lib 1.49.0 → 1.50.0

package/dist/types/agency-pots.d.ts

@@ -0,0 +1,518 @@
+import { type I_AgencyGrantScope } from './agency';
+import type { I_CampaignCreatorIdentity, SettlementForm } from './agency-campaigns';
+/**
+ * Pot campaigns (spec 175 US9): the second way to pay creators on a campaign,
+ * beside the negotiated offer of US7.
+ *
+ * The agency funds ONE pot and sets a maximum per creator; each creator applies
+ * with their own guarantee and rate per 1,000 views; the agency accepts or
+ * declines, never counters (SC-018). Earnings are the guarantee plus the rate
+ * times the counted views, never above the maximum, and accrue only while the
+ * pot has unreserved money (FR-030, FR-032).
+ *
+ * Money is integer minor units plus an ISO-4217 code, everywhere. A creator
+ * never receives a pot-level figure: the only pot-level signal they get is the
+ * two-valued availability (SC-016), fenced by `creatorPotForbiddenKeys`.
+ *
+ * See specs/speckit/175-agency-roster/plan.md → US9 addendum.
+ */
+/** A caption shows this many characters before "more"; the disclosure must sit inside them. */
+export declare const DISCLOSURE_VISIBLE_CHARS = 125;
+export declare const DISCLOSURE_RESULTS: readonly ["pass", "weak", "missing"];
+export type DisclosureResult = (typeof DISCLOSURE_RESULTS)[number];
+export interface I_DisclosureCheck {
+    /**
+     * `pass`: a recommended wording within the first 125 characters.
+     * `weak`: only a bare tag, or a recommended wording placed past the fold.
+     * `missing`: nothing.
+     */
+    result: DisclosureResult;
+    /** The text that was found, as written. */
+    found: string | null;
+    /** Its character index in the caption. */
+    at: number | null;
+}
+export declare const checkDisclosure: (raw: string) => I_DisclosureCheck;
+/** The per-view part for `views`: rate × views / 1000, rounded DOWN to the minor unit. Exact for any size. */
+export declare const potBonusMinor: (ratePer1000Minor: number, views: number) => number;
+export interface I_PotEarningsInput {
+    guaranteeMinor: number;
+    ratePer1000Minor: number;
+    views: number;
+    maxMinor: number;
+}
+/** What a creator's terms earn at `views` with an unlimited pot: never above the maximum. */
+export declare const potEarnings: ({ guaranteeMinor, ratePer1000Minor, views, maxMinor }: I_PotEarningsInput) => number;
+/** The exact view count at which the terms reach the maximum (rounded up), or null when they never do. */
+export declare const potViewsAtMax: ({ guaranteeMinor, ratePer1000Minor, maxMinor }: Omit<I_PotEarningsInput, "views">) => number | null;
+/** Cost per 1,000 views in minor units, rounded half up; null without views. */
+export declare const potCostPer1000Minor: (costMinor: number, views: number) => number | null;
+/**
+ * The currencies a pot may be kept in: every amount is in minor units of two
+ * decimals (grosz, cents), so a zero- or three-decimal currency (JPY, KWD) is
+ * refused rather than shown a hundred times off (review 2026-10-06 L14).
+ */
+export declare const POT_CURRENCIES: readonly ["PLN", "EUR", "USD", "GBP", "CHF", "CZK", "SEK", "NOK", "DKK"];
+export type PotCurrency = (typeof POT_CURRENCIES)[number];
+/** Any key carrying a pot-level figure. A creator-facing response must have none, at any depth. */
+export declare const CREATOR_POT_FORBIDDEN_KEY: RegExp;
+/** The paths of every forbidden key in `value`; empty when the response is clean. */
+export declare const creatorPotForbiddenKeys: (value: unknown, path?: string) => string[];
+/**
+ * An entry is one creator's application on one pot.
+ *   applied → accepted | declined | withdrawn;  accepted → released (left or
+ *   removed before publication).
+ */
+export declare const POT_ENTRY_STATES: readonly ["applied", "accepted", "declined", "withdrawn", "released"];
+export type PotEntryState = (typeof POT_ENTRY_STATES)[number];
+/**
+ * The pot board's columns, in order (design A2): invitation sent, application,
+ * in the campaign, material in, scheduled, bonus counting, bonus final, done
+ * (the keep-up period ended with the post still up).
+ */
+export declare const POT_STEPS: readonly ["invited", "applied", "accepted", "material_in", "scheduled", "counting", "final", "done"];
+export type PotStep = (typeof POT_STEPS)[number];
+/** Rows off the board, kept in the table with their date. */
+export type PotOffBoard = 'declined' | 'withdrawn' | 'released' | 'left' | 'removed' | 'broken';
+export declare const POT_AVAILABILITY: readonly ["full_max_available", "filling_up"];
+export type PotAvailability = (typeof POT_AVAILABILITY)[number];
+/** Why a bonus is held (FR-037): the jump against the creator's own history, or paid delivery ad2app did not start. */
+export declare const POT_HOLD_REASONS: readonly ["jump", "paid_delivery"];
+export type PotHoldReason = (typeof POT_HOLD_REASONS)[number];
+/** The agency's three acts on a held bonus. `message` records the act; the thread opens on the client. */
+export declare const POT_HOLD_ACTIONS: readonly ["approve", "cap", "message"];
+export type PotHoldAction = (typeof POT_HOLD_ACTIONS)[number];
+/** The keep-up check's outcome (FR-032): still up, or taken down before the end. */
+export type PotKeepUpOutcome = 'kept' | 'broken';
+/**
+ * A post taken down after the bonus window but before the keep-up end: the
+ * agency is informed and decides whether the guarantee stays earned (FR-032).
+ * Before the window ends the guarantee is not earned, with no decision.
+ */
+export declare const POT_REMOVAL_DECISIONS: readonly ["keep_base", "withhold_base"];
+export type PotRemovalDecision = (typeof POT_REMOVAL_DECISIONS)[number];
+/** Refusal codes the frontend owes its own copy for. */
+export declare const AGENCY_POT_CODES: {
+    /** Accepting would reserve more than the pot has unreserved. */
+    readonly POT_CANNOT_COVER: "agency-pot-cannot-cover";
+    /** The guarantee must be below the maximum per creator. */
+    readonly GUARANTEE_TOO_HIGH: "agency-pot-guarantee-too-high";
+    /** Applications closed at the application deadline, or the pot was moved. */
+    readonly APPLICATIONS_CLOSED: "agency-pot-applications-closed";
+    /** The kind is fixed once a creator is invited; the terms once an entry is accepted. */
+    readonly POT_LOCKED: "agency-pot-locked";
+    /** A refill above the maximum budget. */
+    readonly ABOVE_MAX_BUDGET: "agency-pot-above-max-budget";
+    /** The caption fails the disclosure check (FR-040). */
+    readonly DISCLOSURE_REQUIRED: "agency-pot-disclosure-required";
+    /** The creator has not connected the platform the post goes to. */
+    readonly NO_ACCOUNT: "agency-pot-no-account";
+    /** The confirmed time is not the one on the row now (the agency moved it meanwhile). */
+    readonly PUBLISH_TIME_CHANGED: "agency-pot-publish-time-changed";
+};
+export type AgencyPotCode = (typeof AGENCY_POT_CODES)[keyof typeof AGENCY_POT_CODES];
+export interface I_PotTerms {
+    guaranteeMinor: number;
+    ratePer1000Minor: number;
+}
+/**
+ * Set once by the agency, pre-filled for the creator (FR-040). A field the
+ * platform does not support is dropped at publish (research/us9/publishing-fields.md).
+ */
+export interface I_PotPublishingSettings {
+    /** Instagram "Paid partnership", TikTok "Branded content", X "Paid partnership". */
+    paidPartnershipLabel: boolean;
+    /** The brand tagged as sponsor on Instagram. */
+    sponsorHandle: string | null;
+    /** A Collab invite to the brand's Instagram account. */
+    collabHandle: string | null;
+    /** A link or a discount code, posted as the first comment. */
+    firstComment: string | null;
+    commentsEnabled: boolean;
+}
+/** The dates on the timeline (FR-036). Bonus and keep-up ends derive from publication due; never set by hand. */
+export interface I_PotSchedule {
+    materialsDueAt: string | null;
+    publicationDueAt: string | null;
+    bonusEndsAt: string | null;
+    keepUpEndsAt: string | null;
+}
+/** The pot's parts. approvedBonus + heldBonus + reservedGuarantees + unreserved = funded, always. */
+export interface I_AgencyPotParts {
+    fundedMinor: number;
+    /** Accepted creators' guarantees, published or not. */
+    reservedGuaranteesMinor: number;
+    /** Per-view bonus accrued and payable. */
+    approvedBonusMinor: number;
+    /** Per-view bonus accrued and held under FR-037: committed, not payable, out of the cost figures. */
+    heldBonusMinor: number;
+    unreservedMinor: number;
+}
+export interface I_AgencyPotView {
+    currency: string;
+    maxBudgetMinor: number;
+    maxPerCreatorMinor: number;
+    bonusWindowDays: number;
+    keepUpMonths: number;
+    goalViews: number | null;
+    coverUrl: string | null;
+    applicationDeadlineAt: string | null;
+    /** Set when the remainder was moved into another campaign: closed to new applications. */
+    movedTo: {
+        campaignId: string;
+        name: string;
+    } | null;
+    publishing: I_PotPublishingSettings;
+    schedule: I_PotSchedule;
+    parts: I_AgencyPotParts;
+    /** floor(funded / max per creator). */
+    creatorsCoveredAtFullMax: number;
+    /** Accepted creators × the maximum: what the pot could owe if every one reached it. */
+    maxCommitmentMinor: number;
+    /** Published creators' guarantees plus approved bonus. */
+    earnedMinor: number;
+    /** Raw readings summed over every row: the totals row. */
+    views: number;
+    /** The goal's progress: raw readings of posts whose bonus is not under review, as the client report counts them (FR-037). */
+    resultViews: number;
+    /** Raw readings of posts whose bonus is under review, named beside the goal and left out of it. */
+    heldViews: number;
+    /** Views the bonus counts toward (capped under FR-037): the cost basis. */
+    countedViews: number;
+    /** Blended cost per 1,000 views over published, unheld rows; null with no views. */
+    blendedCostPer1000Minor: number | null;
+    /** The latest count across the pot; every export is stamped with it. */
+    lastCountAt: string | null;
+}
+/** The FR-037 evidence, in numbers. */
+export interface I_PotHoldEvidence {
+    reason: PotHoldReason;
+    medianViews: number | null;
+    /** views / median, two decimals. */
+    viewsVsMedian: number | null;
+    /** Engagement per view now and usually, as fractions. */
+    engagementNow: number | null;
+    engagementUsual: number | null;
+    jumpViews: number | null;
+    jumpDays: number | null;
+}
+export interface I_PotHold {
+    heldAt: string;
+    evidence: I_PotHoldEvidence;
+    /** null while it waits on the agency. */
+    decision: 'approved' | 'capped' | null;
+    decidedAt: string | null;
+    /** With `capped`: the views the bonus counts to (2 × median). */
+    capViews: number | null;
+    /** What `cap` would leave as bonus, for the button. */
+    cappedBonusMinor: number | null;
+}
+/** Zernio refused the post when ad2app scheduled it: the confirmation is cleared and the creator confirms again. */
+export interface I_PotPublishRefusal {
+    at: string;
+    /** The provider's words, per platform (`tiktok: …; instagram: …`). */
+    reason: string;
+}
+/** One creator's row in the pot table (FR-035). Every total equals the sum of its rows. */
+export interface I_AgencyPotRow {
+    memberId: string;
+    entryId: string | null;
+    creator: I_CampaignCreatorIdentity;
+    step: PotStep | PotOffBoard;
+    stepAt: string;
+    terms: I_PotTerms | null;
+    /** The latest reading; null before publication. */
+    views: number | null;
+    /** Views the bonus counts toward: `views`, stopped at the FR-037 cap when the agency set one. */
+    countedViews: number | null;
+    guaranteeReservedMinor: number;
+    /** Earned so far: the guarantee once published plus approved bonus. */
+    earnedMinor: number;
+    heldBonusMinor: number;
+    /** earned / max, as a fraction; null before publication. */
+    shareOfMax: number | null;
+    costPer1000Minor: number | null;
+    settlementForm: SettlementForm | null;
+    publishAt: string | null;
+    publishConfirmedAt: string | null;
+    publishedAt: string | null;
+    postUrl: string | null;
+    bonusEndsAt: string | null;
+    keepUpEndsAt: string | null;
+    frozen: boolean;
+    /** `needsDecision`: taken down after the bonus window, waiting on the agency's keep-or-withhold (FR-032). */
+    outcome: {
+        kind: PotKeepUpOutcome;
+        lastFoundAt: string | null;
+        decision: PotRemovalDecision | null;
+        needsDecision: boolean;
+    } | null;
+    hold: I_PotHold | null;
+    lastCountAt: string | null;
+    /** The provider refused the post at scheduling, since the time was last set or confirmed; null otherwise. */
+    publishRefusal?: I_PotPublishRefusal | null;
+}
+export interface I_AgencyPotTotals {
+    acceptedCreators: number;
+    reservedGuaranteesMinor: number;
+    views: number;
+    countedViews: number;
+    earnedMinor: number;
+    blendedCostPer1000Minor: number | null;
+}
+/** `GET /agency/campaigns/:id/pot/board` (FR-035). */
+export interface I_AgencyPotBoard {
+    pot: I_AgencyPotView;
+    rows: I_AgencyPotRow[];
+    totals: I_AgencyPotTotals;
+    /** Creators per board column. */
+    steps: Record<PotStep, number>;
+}
+/** The creator's statistics an application shows, from what they shared (FR-035). */
+export interface I_PotCreatorProfile {
+    platforms: Array<{
+        platform: string;
+        followers: number | null;
+    }>;
+    medianViews: number | null;
+    meanViews: number | null;
+    p25Views: number | null;
+    p75Views: number | null;
+    /** Interactions per view over 90 days, as a fraction. */
+    engagement: number | null;
+    posts90: number;
+    recent: Array<{
+        postedAt: string;
+        views: number | null;
+        url: string | null;
+        thumbnailUrl: string | null;
+    }>;
+}
+export type PotScenario = 'none' | 'p25' | 'median' | 'p75' | 'max';
+/** `GET /agency/campaigns/:id/pot/entries/:entryId` while it is an application. */
+export interface I_PotApplicationView {
+    entryId: string;
+    memberId: string;
+    creator: I_CampaignCreatorIdentity;
+    terms: I_PotTerms;
+    appliedAt: string;
+    /**
+     * `shared`: the profile is filled. `not_shared`: no active grant with the
+     * analytics scope, said in words. `unavailable`: the read failed just now;
+     * never shown as zeros.
+     */
+    profileState: 'shared' | 'not_shared' | 'unavailable';
+    /** Set only when `profileState` is `shared`. */
+    profile: I_PotCreatorProfile | null;
+    viewsAtMax: number | null;
+    scenarios: Array<{
+        scenario: PotScenario;
+        views: number | null;
+        costMinor: number | null;
+        costPer1000Minor: number | null;
+    }>;
+    blendedCostPer1000Minor: number | null;
+    unreservedBeforeMinor: number;
+    unreservedAfterMinor: number;
+    /** False when the pot cannot cover the guarantee: accept is refused with POT_CANNOT_COVER. */
+    canAccept: boolean;
+}
+export interface I_CreatorPotEarnings {
+    guaranteeMinor: number;
+    /** Payable per-view bonus. */
+    bonusMinor: number;
+    /** Bonus under review (FR-037): shown with the amount, never as an accusation. */
+    heldBonusMinor: number;
+    totalMinor: number;
+    views: number;
+    lastCountAt: string | null;
+    frozen: boolean;
+}
+export interface I_CreatorPotEntry {
+    state: PotEntryState;
+    terms: I_PotTerms;
+    appliedAt: string;
+    decidedAt: string | null;
+    publishAt: string | null;
+    publishConfirmedAt: string | null;
+    publishedAt: string | null;
+    postUrl: string | null;
+    bonusEndsAt: string | null;
+    keepUpEndsAt: string | null;
+    outcome: PotKeepUpOutcome | null;
+    /** True once the keep-up period ended with the post still up. */
+    mayTakeDown: boolean;
+    /**
+     * A post taken down before the keep-up end (FR-032): inside the bonus window
+     * the guarantee is lost; after it the agency decides, then keeps or returns it.
+     */
+    removal: 'guarantee_lost' | 'agency_deciding' | 'guarantee_kept' | 'guarantee_returned' | null;
+    /** null before publication. */
+    earnings: I_CreatorPotEarnings | null;
+    /** The provider refused the post at scheduling, since the time was last set or confirmed; null otherwise. */
+    publishRefusal?: I_PotPublishRefusal | null;
+}
+/** Attached to `I_CreatorCampaignView.pot` on a pot campaign. */
+export interface I_CreatorPotView {
+    campaignId: string;
+    currency: string;
+    maxPerCreatorMinor: number;
+    bonusWindowDays: number;
+    keepUpMonths: number;
+    coverUrl: string | null;
+    applicationDeadlineAt: string | null;
+    availability: PotAvailability;
+    /** The maximum in the creator's preferred currency, approximate; null with no rate for the day. */
+    approx: {
+        currency: string;
+        maxPerCreatorMinor: number;
+        rateDate: string;
+    } | null;
+    schedule: I_PotSchedule;
+    publishing: I_PotPublishingSettings;
+    entry: I_CreatorPotEntry | null;
+    canApply: boolean;
+    canWithdraw: boolean;
+    canConfirmPublishAt: boolean;
+    /** The creator's own 90-day median views from their shared statistics, for the application estimate; null when unknown. */
+    medianViews: number | null;
+}
+/** One published post in the brand's report. Costs ride along; the page shows them only when the agency ticks them. */
+export interface I_PotReportPost {
+    memberId: string;
+    creator: I_CampaignCreatorIdentity;
+    platform: string | null;
+    publishedAt: string;
+    postUrl: string | null;
+    thumbnailUrl: string | null;
+    caption: string | null;
+    disclosure: I_DisclosureCheck | null;
+    /** Whether the platform's paid-partnership label went out (null: not asked for). */
+    labelApplied: boolean | null;
+    /** A durable ad2app link that opens a fresh signed read of the approved material on every open; null when none. */
+    materialLink: string | null;
+    views: number;
+    likes: number | null;
+    comments: number | null;
+    shares: number | null;
+    saves: number | null;
+    followers: number | null;
+    /** The creator's own 90-day median, when known: each post is judged against its creator. */
+    medianViews: number | null;
+    /** Views by day since publication, as counted (the latest reading of each day). */
+    daily: Array<{
+        day: string;
+        views: number;
+    }>;
+    /** A bonus under review (FR-037): left out of the sums and named as such. */
+    held: boolean;
+    publishedOnTime: boolean | null;
+    keepUpEndsAt: string | null;
+    versions: number;
+    revisionRounds: number;
+    /** The most-liked comments, text and likes only; null when the creator does not share comments. */
+    topComments: Array<{
+        text: string;
+        likes: number;
+    }> | null;
+    earnedMinor: number;
+}
+/** `GET /agency/campaigns/:id/pot/report`. */
+export interface I_PotClientReport {
+    campaign: {
+        id: string;
+        name: string;
+        organizationName: string;
+        brief: string;
+    };
+    currency: string;
+    goalViews: number | null;
+    publicationDueAt: string | null;
+    /** When the bonus window of the campaign closes (publication due + the window): the pacing projection runs to it. */
+    campaignEndsAt: string | null;
+    keepUpMonths: number;
+    generatedAt: string;
+    lastCountAt: string | null;
+    posts: I_PotReportPost[];
+    /** What the published, unheld posts cost: shown only when the agency includes costs. */
+    totalCostMinor: number;
+}
+export interface I_CampaignFile {
+    id: string;
+    fileName: string;
+    contentType: string;
+    sizeBytes: number;
+    uploadedAt: string;
+    uploadedBy: string;
+}
+/** PDF, images, video, office documents and archives; no HTML or SVG (opened in the browser). */
+export declare const CAMPAIGN_FILE_CONTENT_TYPE: RegExp;
+export declare const CAMPAIGN_FILE_MAX_BYTES: number;
+/**
+ * `POST /agency/campaign-invitations/:memberId/application` — the creator's own
+ * terms. Applying from an invitation also joins the campaign, answering any
+ * access request folded into it with `scopes` (absent = everything asked).
+ */
+export declare class ApplyToPotDto {
+    guaranteeMinor: number;
+    ratePer1000Minor: number;
+    scopes?: I_AgencyGrantScope[];
+    constructor(data?: Partial<ApplyToPotDto>);
+}
+/** `POST /agency/campaigns/:id/pot/refill` — up to the maximum budget. */
+export declare class RefillPotDto {
+    amountMinor: number;
+    constructor(data?: Partial<RefillPotDto>);
+}
+/** `PATCH /agency/campaigns/:id/pot/application-deadline`. */
+export declare class MovePotDeadlineDto {
+    applicationDeadlineAt: string;
+    constructor(data?: Partial<MovePotDeadlineDto>);
+}
+/** The agency sets the time agreed with the brand; the creator confirms that same value. */
+export declare class PotPublishAtDto {
+    publishAt: string;
+    constructor(data?: Partial<PotPublishAtDto>);
+}
+export declare class PotHoldActDto {
+    action: PotHoldAction;
+    constructor(data?: Partial<PotHoldActDto>);
+}
+/** `POST /agency/campaigns/:id/pot/entries/:entryId/removal` — the agency's decision on a late takedown (FR-032). */
+export declare class PotRemovalDecisionDto {
+    decision: PotRemovalDecision;
+    constructor(data?: Partial<PotRemovalDecisionDto>);
+}
+/** The caption is the creator's until publication (FR-032). */
+export declare class UpdateMaterialCaptionDto {
+    caption: string;
+    constructor(data?: Partial<UpdateMaterialCaptionDto>);
+}
+export declare class PrepareCampaignFileUploadDto {
+    fileName: string;
+    contentType: string;
+    sizeBytes: number;
+    constructor(data?: Partial<PrepareCampaignFileUploadDto>);
+}
+/** The pot's fields on campaign create (and on a move); flat for the reason given in agency-campaigns.ts. */
+export declare class PotFields {
+    potBudgetMinor?: number;
+    potMaxBudgetMinor?: number;
+    /**
+     * The maximum one creator can earn, guarantee included. Named "cap" on the
+     * wire: a body field matching /creator|user/ reads as a person id to the
+     * agency boundary scan (backend agency-grant-never-opens-inbox.spec.ts).
+     */
+    potCapMinor?: number;
+    potBonusWindowDays?: number;
+    potKeepUpMonths?: number;
+    potGoalViews?: number | null;
+    potCurrency?: string;
+    potApplicationDeadlineAt?: string | null;
+    potPaidPartnershipLabel?: boolean;
+    potSponsorHandle?: string | null;
+    potCollabHandle?: string | null;
+    potFirstComment?: string | null;
+    potCommentsEnabled?: boolean;
+    protected assignPot(data?: Partial<PotFields>): void;
+}