@oxygen-agent/cli 1.1003.12 → 1.1010.644

package/node_modules/@oxygen/shared/dist/signup-lead-payload.js

@@ -0,0 +1,198 @@
+import { isPersonalEmailDomain } from "./freemail-domains.js";
+import { readCoercedString as normalizeString } from "./type-guards.js";
+/**
+ * Classifies an email address into a (likely) company work-email domain.
+ * Consumer/generic mailboxes return `{ domain: null, isGenericMailbox: true }`.
+ */
+export function classifyWorkEmail(email) {
+    if (!email)
+        return { domain: null, isGenericMailbox: false };
+    const at = email.lastIndexOf("@");
+    if (at < 0 || at >= email.length - 1)
+        return { domain: null, isGenericMailbox: false };
+    const domain = email.slice(at + 1).trim().toLowerCase();
+    if (!domain || domain.indexOf(".") < 0)
+        return { domain: null, isGenericMailbox: false };
+    if (isPersonalEmailDomain(domain)) {
+        return { domain: null, isGenericMailbox: true };
+    }
+    return { domain, isGenericMailbox: false };
+}
+export function isGenericMailboxDomain(domain) {
+    if (!domain)
+        return false;
+    return isPersonalEmailDomain(domain);
+}
+export function buildSignupLeadWebhookPayload(input) {
+    const type = normalizeString(input.type) ?? "signup_lead.event";
+    const occurredAt = normalizeDate(input.occurredAt) ?? new Date().toISOString();
+    const eventId = normalizeString(input.eventId) ?? buildFallbackEventId(input, occurredAt);
+    const providerEventId = normalizeString(input.providerEventId) ?? eventId;
+    const eventType = input.lifecycleEvent ?? type;
+    const clerkUserId = normalizeString(input.user?.clerkUserId);
+    const email = normalizeString(input.user?.email)?.toLowerCase() ?? null;
+    const firstName = normalizeString(input.user?.firstName);
+    const lastName = normalizeString(input.user?.lastName);
+    const fullName = normalizeString([firstName, lastName].filter(Boolean).join(" "));
+    const clerkOrgId = normalizeString(input.organization?.clerkOrgId);
+    const companyName = normalizeString(input.organization?.name);
+    // Prefer the explicit Clerk org domain, but most product signups arrive with
+    // no org domain set. Fall back to the work-email domain so downstream
+    // company enrichment (domain -> LinkedIn -> profile) and the Attio company
+    // upsert have a key to work with. Generic mailboxes (gmail, …) stay null.
+    const companyDomain = normalizeString(input.organization?.domain)?.toLowerCase() ??
+        classifyWorkEmail(email).domain ??
+        null;
+    const role = normalizeString(input.membership?.role);
+    const organizationCreatedBy = normalizeString(input.organization?.createdBy);
+    const attribution = buildSignupAttribution(input.metadata);
+    const user = compactRecord({
+        clerk_user_id: clerkUserId,
+        email,
+        first_name: firstName,
+        last_name: lastName,
+        full_name: fullName,
+        created_at: normalizeDate(input.user?.createdAt),
+        linkedin_url: normalizeString(input.user?.linkedinUrl) ?? undefined,
+    });
+    const organization = compactRecord({
+        clerk_org_id: clerkOrgId,
+        name: companyName,
+        slug: normalizeString(input.organization?.slug),
+        domain: companyDomain,
+        created_at: normalizeDate(input.organization?.createdAt),
+        created_by: organizationCreatedBy,
+    });
+    const membership = compactRecord({ role });
+    const stripe = input.stripe
+        ? compactRecord({
+            customer_id: normalizeString(input.stripe.customerId),
+            subscription_id: normalizeString(input.stripe.subscriptionId),
+            invoice_id: normalizeString(input.stripe.invoiceId),
+            price_id: normalizeString(input.stripe.priceId),
+            tier: normalizeString(input.stripe.tier),
+            status: normalizeString(input.stripe.status),
+            trial_start: normalizeDate(input.stripe.trialStart),
+            trial_end: normalizeDate(input.stripe.trialEnd),
+            period_start: normalizeDate(input.stripe.periodStart),
+            period_end: normalizeDate(input.stripe.periodEnd),
+            amount_paid: input.stripe.amountPaid ?? undefined,
+            currency: normalizeString(input.stripe.currency)?.toLowerCase(),
+            billing_reason: normalizeString(input.stripe.billingReason),
+        })
+        : undefined;
+    const payload = compactRecord({
+        event_id: eventId,
+        event_type: eventType,
+        provider_event_id: providerEventId,
+        provider_event_type: type,
+        event: type,
+        type,
+        occurred_at: occurredAt,
+        source: input.source,
+        user,
+        person: user,
+        organization,
+        membership,
+        stripe,
+        metadata: input.metadata,
+        attribution,
+        qualification_evidence: input.qualificationEvidence,
+        research: input.research,
+        raw_event: input.rawEvent,
+    });
+    return compactRecord({
+        id: eventId,
+        event_id: eventId,
+        event_type: eventType,
+        provider_event_id: providerEventId,
+        provider_event_type: type,
+        event: type,
+        type,
+        occurred_at: occurredAt,
+        timestamp: occurredAt,
+        source: input.source,
+        provider: input.source,
+        clerk_user_id: clerkUserId,
+        clerk_org_id: clerkOrgId,
+        email,
+        first_name: firstName,
+        last_name: lastName,
+        full_name: fullName,
+        company_name: companyName,
+        company_domain: companyDomain,
+        organization_created_by: organizationCreatedBy,
+        person_linkedin_url: normalizeString(input.user?.linkedinUrl) ?? undefined,
+        role,
+        stripe_customer_id: normalizeString(input.stripe?.customerId),
+        stripe_subscription_id: normalizeString(input.stripe?.subscriptionId),
+        stripe_invoice_id: normalizeString(input.stripe?.invoiceId),
+        user,
+        person: user,
+        organization,
+        membership,
+        stripe,
+        metadata: input.metadata,
+        attribution,
+        qualification_evidence: input.qualificationEvidence,
+        research: input.research,
+        raw_event: input.rawEvent,
+        payload,
+    });
+}
+function buildSignupAttribution(metadata) {
+    if (!metadata)
+        return undefined;
+    const publicMetadata = recordValue(metadata.clerk_public_metadata);
+    const unsafeMetadata = recordValue(metadata.clerk_unsafe_metadata);
+    const combined = { ...unsafeMetadata, ...publicMetadata, ...metadata };
+    const selfReported = Array.isArray(combined.attribution_sources)
+        ? combined.attribution_sources.filter((value) => typeof value === "string" && value.trim().length > 0)
+        : [];
+    const result = compactRecord({
+        self_reported_sources: selfReported.length > 0 ? selfReported : undefined,
+        self_reported_other: normalizeString(combined.attribution_other) ?? undefined,
+        linkedin_url: firstStringValue(combined.linkedin_url, combined.linkedin_profile_url) ?? undefined,
+        landing_page: firstStringValue(combined.landing_page, combined.landing_page_url) ?? undefined,
+        referrer: firstStringValue(combined.referrer, combined.referrer_url) ?? undefined,
+        utm_source: normalizeString(combined.utm_source) ?? undefined,
+        utm_medium: normalizeString(combined.utm_medium) ?? undefined,
+        utm_campaign: normalizeString(combined.utm_campaign) ?? undefined,
+        utm_content: normalizeString(combined.utm_content) ?? undefined,
+        utm_term: normalizeString(combined.utm_term) ?? undefined,
+    });
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+function buildFallbackEventId(input, occurredAt) {
+    const identity = normalizeString(input.user?.clerkUserId) ??
+        normalizeString(input.organization?.clerkOrgId) ??
+        normalizeString(input.user?.email) ??
+        normalizeString(input.organization?.domain) ??
+        "unknown";
+    return `signup_lead:${input.source}:${input.type}:${identity}:${occurredAt}`;
+}
+function compactRecord(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}
+function normalizeDate(value) {
+    if (value === null || value === undefined)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function stringValue(value) {
+    return normalizeString(value);
+}
+function firstStringValue(...values) {
+    for (const value of values) {
+        const normalized = stringValue(value);
+        if (normalized)
+            return normalized;
+    }
+    return null;
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}

package/node_modules/@oxygen/shared/dist/social-capabilities.d.ts

@@ -26,6 +26,12 @@ export type SocialMetricCapability = {
     status: SocialCapabilityStatus;
     provider_field: string | null;
     reason: string | null;
+    /**
+     * `author_private` metrics are shown by the network only to the post's author
+     * (LinkedIn impressions). They never leave the author's own workspace — a UGC
+     * program master sees public telemetry only.
+     */
+    visibility: "public" | "author_private";
 };
 export type SocialCapabilityProfile = {
     version: 1;

package/node_modules/@oxygen/shared/dist/social-capabilities.js

@@ -39,9 +39,11 @@ const LINKEDIN_UNIPILE_CAPABILITIES = {
         read_post_metrics: {
             status: "limited",
             source: "provider",
-            provider_operation: "linkedin.posts_get",
+            // Owned-post discovery pages carry every post's counters; `linkedin.posts_get`
+            // is the per-post fallback for posts discovery has not seen recently.
+            provider_operation: "linkedin.users_posts",
             external_write: false,
-            limitation: "coarse_public_counters_only",
+            limitation: "owned_posts_author_analytics",
         },
         list_comments: {
             status: "available",
@@ -59,14 +61,19 @@ const LINKEDIN_UNIPILE_CAPABILITIES = {
         },
     },
     metrics: {
-        impressions: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
-        reactions: { status: "available", provider_field: "reaction_counter", reason: null },
-        comments: { status: "available", provider_field: "comment_counter", reason: null },
-        reposts: { status: "available", provider_field: "repost_counter", reason: null },
-        saves: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
-        sends: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
-        clicks: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
-        video_views: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
+        impressions: {
+            status: "limited",
+            provider_field: "analytics.impressions_counter",
+            reason: "author_analytics_when_returned",
+            visibility: "author_private",
+        },
+        reactions: { status: "available", provider_field: "reactions_counter[].count", reason: null, visibility: "public" },
+        comments: { status: "available", provider_field: "comments_counter", reason: null, visibility: "public" },
+        reposts: { status: "available", provider_field: "reposts_counter", reason: null, visibility: "public" },
+        saves: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE, visibility: "public" },
+        sends: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE, visibility: "public" },
+        clicks: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE, visibility: "author_private" },
+        video_views: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE, visibility: "public" },
     },
     ingestion: {
         polling: true,
@@ -108,21 +115,23 @@ const X_COMPOSIO_CAPABILITIES = {
         },
     },
     metrics: {
-        impressions: { status: "available", provider_field: "public_metrics.impression_count", reason: null },
-        reactions: { status: "available", provider_field: "public_metrics.like_count", reason: null },
-        comments: { status: "available", provider_field: "public_metrics.reply_count", reason: null },
-        reposts: { status: "available", provider_field: "public_metrics.retweet_count", reason: null },
-        saves: { status: "available", provider_field: "public_metrics.bookmark_count", reason: null },
-        sends: { status: "unavailable", provider_field: null, reason: "not_exposed_by_x_post_lookup" },
+        impressions: { status: "available", provider_field: "public_metrics.impression_count", reason: null, visibility: "public" },
+        reactions: { status: "available", provider_field: "public_metrics.like_count", reason: null, visibility: "public" },
+        comments: { status: "available", provider_field: "public_metrics.reply_count", reason: null, visibility: "public" },
+        reposts: { status: "available", provider_field: "public_metrics.retweet_count", reason: null, visibility: "public" },
+        saves: { status: "available", provider_field: "public_metrics.bookmark_count", reason: null, visibility: "public" },
+        sends: { status: "unavailable", provider_field: null, reason: "not_exposed_by_x_post_lookup", visibility: "public" },
         clicks: {
             status: "limited",
             provider_field: "non_public_metrics.url_link_clicks",
             reason: "owned_posts_user_context_30_day_window",
+            visibility: "author_private",
         },
         video_views: {
             status: "limited",
             provider_field: "includes.media[].public_metrics.view_count",
             reason: "video_media_only",
+            visibility: "public",
         },
     },
     ingestion: {

package/node_modules/@oxygen/shared/dist/social-post-metrics-core.d.ts

@@ -0,0 +1,32 @@
+import type { SocialPostMetric } from "./social-capabilities.js";
+/**
+ * One provider read of a post's engagement, parsed into the registry vocabulary.
+ *
+ * Every value is a cumulative counter as of the read. An ABSENT key means the
+ * provider did not return that metric on this read; it is never a zero. A zero is
+ * only ever the provider saying "nobody did this".
+ */
+export type ParsedSocialPostMetrics = {
+    metrics: Partial<Record<SocialPostMetric, number>>;
+    /** Channel-specific counters outside the canonical registry (same absent-key rule). */
+    extended: Record<string, number>;
+    /** Which provider payload shape was recognised, e.g. `unipile_v2`. */
+    shape: string;
+    /**
+     * False when the counters describe someone else's post — a LinkedIn repost
+     * carries the ORIGINAL post's reactions and comments. Such a read must never be
+     * attributed to the reposting account's performance.
+     */
+    attributable: boolean;
+    /** Metrics the provider returned but a plausibility guard refused. */
+    rejected: SocialPostMetric[];
+};
+/**
+ * A count the provider actually returned. Absent / null / non-numeric / negative
+ * all collapse to null — never to 0.
+ */
+export declare function readMetricCount(value: unknown): number | null;
+/** First key that carries a usable count; null when none did. */
+export declare function pickMetricCount(record: Record<string, unknown>, keys: readonly string[]): number | null;
+/** Drop nulls so an absent metric stays an absent key. */
+export declare function presentMetrics<K extends string>(values: Record<K, number | null>): Partial<Record<K, number>>;

package/node_modules/@oxygen/shared/dist/social-post-metrics-core.js

@@ -0,0 +1,32 @@
+/**
+ * A count the provider actually returned. Absent / null / non-numeric / negative
+ * all collapse to null — never to 0.
+ */
+export function readMetricCount(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value >= 0 ? Math.trunc(value) : null;
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) && parsed >= 0 ? Math.trunc(parsed) : null;
+    }
+    return null;
+}
+/** First key that carries a usable count; null when none did. */
+export function pickMetricCount(record, keys) {
+    for (const key of keys) {
+        const value = readMetricCount(record[key]);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
+/** Drop nulls so an absent metric stays an absent key. */
+export function presentMetrics(values) {
+    const present = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== null)
+            present[key] = value;
+    }
+    return present;
+}

package/node_modules/@oxygen/shared/dist/social-post-metrics-linkedin.d.ts

@@ -0,0 +1,31 @@
+import { type ParsedSocialPostMetrics } from "./social-post-metrics-core.js";
+/**
+ * Bump when the parse of a stored LinkedIn payload changes meaning, so stored raw
+ * payloads can be re-derived.
+ */
+export declare const LINKEDIN_UNIPILE_POST_METRICS_PARSER_VERSION = 2;
+/**
+ * Parse a LinkedIn post object returned by Unipile (`users_posts` list items and
+ * `posts_get` share the shape).
+ *
+ * Unipile's v1 DOCUMENTATION names the counters `reaction_counter`,
+ * `comment_counter` and `repost_counter`. The v2 API, which the v2 adapter passes
+ * through un-normalized, actually returns:
+ *
+ *   reactions_counter  [{ reaction, count }]   one entry per reaction type
+ *   comments_counter   number
+ *   reposts_counter    number
+ *   analytics          { impressions_counter, page_viewers_from_this_post_counter,
+ *                        followers_gained_from_this_post_counter }  — author-only
+ *
+ * Parsing the documented names against the real payload stored 5,172 production
+ * snapshots with every metric NULL (2026-09-23). Parsers here are pinned to
+ * redacted REAL payloads, never to vendor documentation.
+ *
+ * Impressions are read ONLY from the `analytics` object, which LinkedIn returns to
+ * the post's author. The v1 documentation's top-level `impressions_counter` is a
+ * placeholder zero and stays ignored. A repost's counters belong to the original
+ * post, so a repost is parsed but marked non-attributable.
+ */
+export declare function parseLinkedInUnipilePostMetrics(payload: Record<string, unknown>): ParsedSocialPostMetrics;
+export declare function linkedInUnipileMetricEvidence(payload: Record<string, unknown>): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/social-post-metrics-linkedin.js

@@ -0,0 +1,103 @@
+import { pickMetricCount, presentMetrics, readMetricCount, } from "./social-post-metrics-core.js";
+import { isRecord } from "./type-guards.js";
+/**
+ * Bump when the parse of a stored LinkedIn payload changes meaning, so stored raw
+ * payloads can be re-derived.
+ */
+export const LINKEDIN_UNIPILE_POST_METRICS_PARSER_VERSION = 2;
+/**
+ * Parse a LinkedIn post object returned by Unipile (`users_posts` list items and
+ * `posts_get` share the shape).
+ *
+ * Unipile's v1 DOCUMENTATION names the counters `reaction_counter`,
+ * `comment_counter` and `repost_counter`. The v2 API, which the v2 adapter passes
+ * through un-normalized, actually returns:
+ *
+ *   reactions_counter  [{ reaction, count }]   one entry per reaction type
+ *   comments_counter   number
+ *   reposts_counter    number
+ *   analytics          { impressions_counter, page_viewers_from_this_post_counter,
+ *                        followers_gained_from_this_post_counter }  — author-only
+ *
+ * Parsing the documented names against the real payload stored 5,172 production
+ * snapshots with every metric NULL (2026-09-23). Parsers here are pinned to
+ * redacted REAL payloads, never to vendor documentation.
+ *
+ * Impressions are read ONLY from the `analytics` object, which LinkedIn returns to
+ * the post's author. The v1 documentation's top-level `impressions_counter` is a
+ * placeholder zero and stays ignored. A repost's counters belong to the original
+ * post, so a repost is parsed but marked non-attributable.
+ */
+export function parseLinkedInUnipilePostMetrics(payload) {
+    const analytics = isRecord(payload.analytics) ? payload.analytics : null;
+    const shape = "reactions_counter" in payload || "comments_counter" in payload || "reposts_counter" in payload
+        ? "unipile_v2"
+        : "reaction_counter" in payload || "comment_counter" in payload || "repost_counter" in payload
+            ? "unipile_v1"
+            : "unknown";
+    const reactions = reactionTotal(payload.reactions_counter)
+        ?? pickMetricCount(payload, ["reaction_counter", "reaction_count", "reactions_count", "likes_count"]);
+    const comments = pickMetricCount(payload, ["comments_counter", "comment_counter", "comment_count", "comments_count"]);
+    const reposts = pickMetricCount(payload, ["reposts_counter", "repost_counter", "repost_count", "share_count", "shares_count"]);
+    let impressions = analytics ? pickMetricCount(analytics, ["impressions_counter", "impressions"]) : null;
+    const rejected = [];
+    const engagements = (reactions ?? 0) + (comments ?? 0) + (reposts ?? 0);
+    // Every reaction, comment and repost came from a member who saw the post, so an
+    // impression count below them is not a measurement we can stand behind.
+    if (impressions !== null && impressions < engagements) {
+        impressions = null;
+        rejected.push("impressions");
+    }
+    return {
+        metrics: presentMetrics({ reactions, comments, reposts, impressions }),
+        extended: presentMetrics({
+            followers_gained: analytics ? readMetricCount(analytics.followers_gained_from_this_post_counter) : null,
+            page_viewers: analytics ? readMetricCount(analytics.page_viewers_from_this_post_counter) : null,
+        }),
+        shape,
+        attributable: payload.is_repost !== true,
+        rejected,
+    };
+}
+/**
+ * Every field the LinkedIn parse reads, and nothing else: enough to re-derive the
+ * metrics after a parser fix, without storing the post's text, author or media.
+ */
+const LINKEDIN_METRIC_EVIDENCE_KEYS = [
+    "id", "social_id", "object", "is_repost", "created_at", "date",
+    "reactions_counter", "comments_counter", "reposts_counter", "analytics",
+    "reaction_counter", "comment_counter", "repost_counter",
+    "reaction_count", "reactions_count", "likes_count", "comment_count", "comments_count",
+    "repost_count", "share_count", "shares_count",
+];
+export function linkedInUnipileMetricEvidence(payload) {
+    const evidence = {};
+    for (const key of LINKEDIN_METRIC_EVIDENCE_KEYS) {
+        if (key in payload)
+            evidence[key] = payload[key];
+    }
+    return evidence;
+}
+/** v2 carries one `{reaction, count}` entry per reaction type; v1 a single number. */
+function reactionTotal(value) {
+    const direct = readMetricCount(value);
+    if (direct !== null)
+        return direct;
+    if (!Array.isArray(value))
+        return null;
+    // An empty list is the provider stating "no reactions of any type".
+    if (value.length === 0)
+        return 0;
+    let total = 0;
+    let found = false;
+    for (const item of value) {
+        if (!isRecord(item))
+            continue;
+        const count = readMetricCount(item.count);
+        if (count === null)
+            continue;
+        total += count;
+        found = true;
+    }
+    return found ? total : null;
+}

package/node_modules/@oxygen/shared/dist/social-post-metrics-series.d.ts

@@ -0,0 +1,96 @@
+import type { SocialPostMetric } from "./social-capabilities.js";
+/**
+ * Engagement EARNED per day, derived from cumulative provider counters.
+ *
+ * A provider only ever reports a post's running total. What a founder asks —
+ * "how many people did my posts reach this week, and is that growing?" — is the
+ * DIFFERENCE between reads, attributed to the days it happened in. The rules:
+ *
+ * - Every counter is 0 at publish, so the publish instant is the first point.
+ * - An observation is flat from `observedAt` through `confirmedAt`; only the gap
+ *   from one observation's `confirmedAt` to the next one's `observedAt` is unknown.
+ * - A delta whose unknown gap is at most `maxProrateMs` is spread across the days
+ *   of that gap in proportion to time and flagged `estimated` when it spans more
+ *   than one day. A longer gap (a post discovered weeks after publishing, a sync
+ *   outage) is NOT smeared across days: its share inside the window is reported as
+ *   `unattributed`, because pretending to know which day it happened on would be a
+ *   confident-looking lie.
+ * - A negative delta (a deleted comment) is kept, so totals stay net-correct, and
+ *   counted in `decreases`.
+ * - A day no post was tracked on is a gap (`null`), never a zero.
+ */
+export type MetricObservationPoint = {
+    observedAt: Date;
+    confirmedAt: Date;
+    metrics: Partial<Record<SocialPostMetric, number>>;
+};
+export type PostMetricTimeline = {
+    publishedAt: Date | null;
+    /** Ascending by observedAt. */
+    observations: MetricObservationPoint[];
+};
+export type EarnedDay = {
+    /** Local calendar date in the requested time zone. */
+    date: string;
+    value: number | null;
+    estimated: boolean;
+    postsTracked: number;
+};
+export type EarnedWindow = {
+    days: EarnedDay[];
+    /** Sum of the day values plus `unattributed`; null when nothing was tracked. */
+    total: number | null;
+    /** Earned inside the window across gaps too long to place on a day. */
+    unattributed: number;
+    decreases: number;
+    postsReporting: number;
+};
+export declare const EARNED_SERIES_MAX_PRORATE_MS: number;
+/**
+ * Earned per day for one metric, or the sum of several (engagements), across a
+ * set of posts. `dayStarts` are the instants each local day begins; `windowEnd`
+ * closes the last day.
+ */
+export declare function computeEarnedWindow(input: {
+    timelines: readonly PostMetricTimeline[];
+    metrics: readonly SocialPostMetric[];
+    dayStarts: readonly {
+        date: string;
+        start: Date;
+    }[];
+    windowEnd: Date;
+    maxProrateMs?: number;
+}): EarnedWindow;
+export type ValueAtAge = {
+    value: number;
+    interpolated: boolean;
+};
+/**
+ * A post's cumulative metric (or sum of metrics) exactly `ageMs` after publishing,
+ * so posts can be compared at the same age ("impressions after 24 hours"). Exact
+ * inside a known-flat interval; interpolated linearly across a gap no longer than
+ * `maxProrateMs`; null when the age falls in a longer gap, before the first read,
+ * after the last confirmed read, or when the post has no publish time.
+ */
+export declare function valueAtAge(input: {
+    timeline: PostMetricTimeline;
+    metrics: readonly SocialPostMetric[];
+    ageMs: number;
+    maxProrateMs?: number;
+}): ValueAtAge | null;
+/** Median of the values, or null for none. */
+export declare function medianOf(values: readonly number[]): number | null;
+/**
+ * The instant each calendar day in [fromDate, toDate] (inclusive, YYYY-MM-DD)
+ * starts in `timeZone`, plus the instant after the last day. DST-safe: each start
+ * is resolved against that day's own offset.
+ */
+export declare function zonedDayStarts(fromDate: string, toDate: string, timeZone: string): {
+    days: {
+        date: string;
+        start: Date;
+    }[];
+    end: Date;
+};
+/** An IANA zone Intl accepts, or null. Validated here so Postgres never sees a bad one. */
+export declare function validTimeZone(value: string | null | undefined): string | null;