@oxygen-agent/cli 1.1003.12 → 1.1010.1

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

@@ -0,0 +1,213 @@
+export const EARNED_SERIES_MAX_PRORATE_MS = 3 * 24 * 60 * 60 * 1000;
+function pointsFor(timeline, metric) {
+    const points = [];
+    const first = timeline.observations.find((observation) => observation.metrics[metric] !== undefined);
+    if (!first)
+        return points;
+    if (timeline.publishedAt && timeline.publishedAt.getTime() <= first.observedAt.getTime()) {
+        points.push({ from: timeline.publishedAt.getTime(), to: timeline.publishedAt.getTime(), value: 0, anchor: true });
+    }
+    for (const observation of timeline.observations) {
+        const value = observation.metrics[metric];
+        if (value === undefined)
+            continue;
+        points.push({ from: observation.observedAt.getTime(), to: observation.confirmedAt.getTime(), value, anchor: false });
+    }
+    return points;
+}
+/**
+ * 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 function computeEarnedWindow(input) {
+    const maxProrateMs = input.maxProrateMs ?? EARNED_SERIES_MAX_PRORATE_MS;
+    const bounds = input.dayStarts.map((day, index) => ({
+        date: day.date,
+        start: day.start.getTime(),
+        end: (input.dayStarts[index + 1]?.start ?? input.windowEnd).getTime(),
+    }));
+    const windowStart = bounds[0]?.start ?? input.windowEnd.getTime();
+    const windowEnd = input.windowEnd.getTime();
+    const values = bounds.map(() => 0);
+    const estimated = bounds.map(() => false);
+    const tracked = bounds.map(() => new Set());
+    let unattributed = 0;
+    let decreases = 0;
+    let reporting = 0;
+    input.timelines.forEach((timeline, postIndex) => {
+        let reports = false;
+        for (const metric of input.metrics) {
+            const points = pointsFor(timeline, metric);
+            if (points.length === 0)
+                continue;
+            reports = true;
+            // A post is tracked on a day only where its earning is known: a flat
+            // interval it was observed through, or a short gap between two reads.
+            const markTracked = (from, to) => {
+                bounds.forEach((day, index) => {
+                    if (day.start <= to && day.end > from)
+                        tracked[index].add(postIndex);
+                });
+            };
+            for (const point of points)
+                if (!point.anchor)
+                    markTracked(point.from, point.to);
+            for (let index = 1; index < points.length; index += 1) {
+                const previous = points[index - 1];
+                const current = points[index];
+                const delta = current.value - previous.value;
+                if (delta === 0)
+                    continue;
+                if (delta < 0)
+                    decreases += 1;
+                const gapStart = Math.min(previous.to, current.from);
+                const gapEnd = current.from;
+                const gap = gapEnd - gapStart;
+                if (gap <= 0) {
+                    const day = bounds.findIndex((bound) => gapEnd >= bound.start && gapEnd < bound.end);
+                    if (day >= 0)
+                        values[day] += delta;
+                    continue;
+                }
+                const insideWindow = Math.max(0, Math.min(gapEnd, windowEnd) - Math.max(gapStart, windowStart));
+                if (insideWindow === 0)
+                    continue;
+                if (gap > maxProrateMs) {
+                    unattributed += delta * (insideWindow / gap);
+                    continue;
+                }
+                markTracked(gapStart, gapEnd);
+                let spannedDays = 0;
+                bounds.forEach((bound, day) => {
+                    const overlap = Math.max(0, Math.min(gapEnd, bound.end) - Math.max(gapStart, bound.start));
+                    if (overlap === 0)
+                        return;
+                    spannedDays += 1;
+                    values[day] += delta * (overlap / gap);
+                });
+                if (spannedDays > 1 || insideWindow < gap) {
+                    bounds.forEach((bound, day) => {
+                        if (Math.min(gapEnd, bound.end) > Math.max(gapStart, bound.start))
+                            estimated[day] = true;
+                    });
+                }
+            }
+        }
+        if (reports)
+            reporting += 1;
+    });
+    const days = bounds.map((bound, index) => ({
+        date: bound.date,
+        value: tracked[index].size > 0 ? Math.round(values[index]) : null,
+        estimated: tracked[index].size > 0 && estimated[index],
+        postsTracked: tracked[index].size,
+    }));
+    // Round the window once from unrounded parts: per-day rounding would let a net
+    // change of -2 spread over two half-days read as -1.
+    const anyTracked = tracked.some((posts) => posts.size > 0);
+    const trackedSum = values.reduce((sum, value, index) => sum + (tracked[index].size > 0 ? value : 0), 0);
+    return {
+        days,
+        total: anyTracked || Math.round(unattributed) !== 0 ? Math.round(trackedSum + unattributed) : null,
+        unattributed: Math.round(unattributed),
+        decreases,
+        postsReporting: reporting,
+    };
+}
+/**
+ * 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 function valueAtAge(input) {
+    if (!input.timeline.publishedAt)
+        return null;
+    const maxProrateMs = input.maxProrateMs ?? EARNED_SERIES_MAX_PRORATE_MS;
+    const target = input.timeline.publishedAt.getTime() + input.ageMs;
+    let total = 0;
+    let interpolated = false;
+    for (const metric of input.metrics) {
+        const points = pointsFor(input.timeline, metric);
+        if (points.length === 0)
+            return null;
+        let found = null;
+        for (let index = 0; index < points.length && found === null; index += 1) {
+            const point = points[index];
+            if (target >= point.from && target <= point.to) {
+                found = point.value;
+                break;
+            }
+            const next = points[index + 1];
+            if (next && target > point.to && target < next.from) {
+                const gap = next.from - point.to;
+                if (gap > maxProrateMs)
+                    return null;
+                found = point.value + (next.value - point.value) * ((target - point.to) / gap);
+                interpolated = true;
+            }
+        }
+        if (found === null)
+            return null;
+        total += found;
+    }
+    return { value: Math.round(total), interpolated };
+}
+/** Median of the values, or null for none. */
+export function medianOf(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[middle] : Math.round((sorted[middle - 1] + sorted[middle]) / 2);
+}
+/**
+ * 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 function zonedDayStarts(fromDate, toDate, timeZone) {
+    const days = [];
+    const cursor = new Date(`${fromDate}T00:00:00.000Z`);
+    const last = new Date(`${toDate}T00:00:00.000Z`);
+    while (cursor.getTime() <= last.getTime()) {
+        const date = cursor.toISOString().slice(0, 10);
+        days.push({ date, start: startOfZonedDay(date, timeZone) });
+        cursor.setUTCDate(cursor.getUTCDate() + 1);
+    }
+    return { days, end: startOfZonedDay(cursor.toISOString().slice(0, 10), timeZone) };
+}
+function zoneOffsetMs(instant, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    }).formatToParts(instant);
+    const read = (type) => Number(parts.find((part) => part.type === type)?.value ?? 0);
+    const asUtc = Date.UTC(read("year"), read("month") - 1, read("day"), read("hour"), read("minute"), read("second"));
+    return asUtc - Math.floor(instant.getTime() / 1000) * 1000;
+}
+function startOfZonedDay(date, timeZone) {
+    const utcMidnight = new Date(`${date}T00:00:00.000Z`).getTime();
+    const firstGuess = utcMidnight - zoneOffsetMs(new Date(utcMidnight), timeZone);
+    return new Date(utcMidnight - zoneOffsetMs(new Date(firstGuess), timeZone));
+}
+/** An IANA zone Intl accepts, or null. Validated here so Postgres never sees a bad one. */
+export function validTimeZone(value) {
+    if (!value)
+        return null;
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+        return value;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+import { type ParsedSocialPostMetrics } from "./social-post-metrics-core.js";
+export declare const X_COMPOSIO_POST_METRICS_PARSER_VERSION = 1;
+/**
+ * Every field the X parse reads, and nothing else: the post's and its media's
+ * metric blocks, without the post text or author.
+ */
+export declare function xComposioMetricEvidence(payload: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Map an X v2 post lookup (through Composio) into the registry vocabulary. X post
+ * lookup exposes no send/share-via-DM counter, and link clicks only come back in
+ * the author's user context.
+ */
+export declare function parseXComposioPostMetrics(payload: Record<string, unknown>): ParsedSocialPostMetrics;

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

@@ -0,0 +1,78 @@
+import { pickMetricCount, presentMetrics, } from "./social-post-metrics-core.js";
+import { isRecord } from "./type-guards.js";
+export const X_COMPOSIO_POST_METRICS_PARSER_VERSION = 1;
+function xPostEnvelope(payload) {
+    const firstData = isRecord(payload.data) ? payload.data : payload;
+    const post = isRecord(firstData.data) ? firstData.data : firstData;
+    const includes = isRecord(payload.includes)
+        ? payload.includes
+        : isRecord(firstData.includes)
+            ? firstData.includes
+            : {};
+    return { post, includes };
+}
+function sumXMediaViews(includes) {
+    const media = Array.isArray(includes.media) ? includes.media : [];
+    let total = 0;
+    let found = false;
+    for (const item of media) {
+        if (!isRecord(item))
+            continue;
+        const publicMetrics = isRecord(item.public_metrics) ? item.public_metrics : {};
+        const nonPublicMetrics = isRecord(item.non_public_metrics) ? item.non_public_metrics : {};
+        const organicMetrics = isRecord(item.organic_metrics) ? item.organic_metrics : {};
+        const count = pickMetricCount({ ...organicMetrics, ...nonPublicMetrics, ...publicMetrics }, ["view_count", "video_view_count"]);
+        if (count === null)
+            continue;
+        total += count;
+        found = true;
+    }
+    return found ? total : null;
+}
+const X_METRIC_FIELDS = ["public_metrics", "non_public_metrics", "organic_metrics"];
+function pickMetricFields(record, identity) {
+    const picked = {};
+    for (const key of [...identity, ...X_METRIC_FIELDS]) {
+        if (key in record)
+            picked[key] = record[key];
+    }
+    return picked;
+}
+/**
+ * Every field the X parse reads, and nothing else: the post's and its media's
+ * metric blocks, without the post text or author.
+ */
+export function xComposioMetricEvidence(payload) {
+    const { post, includes } = xPostEnvelope(payload);
+    const media = Array.isArray(includes.media)
+        ? includes.media.filter(isRecord).map((item) => pickMetricFields(item, ["media_key", "type"]))
+        : [];
+    return { data: pickMetricFields(post, ["id"]), ...(media.length > 0 ? { includes: { media } } : {}) };
+}
+/**
+ * Map an X v2 post lookup (through Composio) into the registry vocabulary. X post
+ * lookup exposes no send/share-via-DM counter, and link clicks only come back in
+ * the author's user context.
+ */
+export function parseXComposioPostMetrics(payload) {
+    const { post, includes } = xPostEnvelope(payload);
+    const publicMetrics = isRecord(post.public_metrics) ? post.public_metrics : {};
+    const nonPublicMetrics = isRecord(post.non_public_metrics) ? post.non_public_metrics : {};
+    const organicMetrics = isRecord(post.organic_metrics) ? post.organic_metrics : {};
+    const privateMetrics = { ...organicMetrics, ...nonPublicMetrics };
+    return {
+        metrics: presentMetrics({
+            impressions: pickMetricCount(publicMetrics, ["impression_count"]),
+            reactions: pickMetricCount(publicMetrics, ["like_count"]),
+            comments: pickMetricCount(publicMetrics, ["reply_count"]),
+            reposts: pickMetricCount(publicMetrics, ["retweet_count", "repost_count"]),
+            saves: pickMetricCount(publicMetrics, ["bookmark_count"]),
+            clicks: pickMetricCount(privateMetrics, ["url_link_clicks"]),
+            video_views: sumXMediaViews(includes),
+        }),
+        extended: {},
+        shape: isRecord(post.public_metrics) ? "x_v2_lookup" : "unknown",
+        attributable: true,
+        rejected: [],
+    };
+}

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

@@ -0,0 +1,36 @@
+import { type SocialPostMetric } from "./social-capabilities.js";
+import type { ParsedSocialPostMetrics } from "./social-post-metrics-core.js";
+export type { ParsedSocialPostMetrics } from "./social-post-metrics-core.js";
+/** Null when no parser is registered for the pair. */
+export declare function parseSocialPostMetrics(input: {
+    channel: string;
+    providerRail: string;
+    payload: Record<string, unknown>;
+}): ParsedSocialPostMetrics | null;
+export declare function socialPostMetricsParserVersion(channel: string, providerRail: string): number | null;
+/**
+ * The metric-bearing subset of a payload, stored with each observation so a
+ * parser fix can re-derive it without keeping post text, authors or media.
+ * Unknown pairs keep nothing.
+ */
+export declare function socialPostMetricEvidence(input: {
+    channel: string;
+    providerRail: string;
+    payload: Record<string, unknown>;
+}): Record<string, unknown>;
+/** Every registered (channel, provider rail) pair with its current parser version. */
+export declare function listSocialPostMetricsParsers(): Array<{
+    channel: string;
+    providerRail: string;
+    version: number;
+}>;
+/**
+ * Metrics the registry declares fully `available` for the pair that a parse did
+ * not produce. A non-empty answer on a real provider read is parser drift — the
+ * failure that silently stored every LinkedIn metric as NULL twice.
+ */
+export declare function missingDeclaredPostMetrics(input: {
+    channel: string;
+    providerRail: string;
+    parsed: ParsedSocialPostMetrics;
+}): SocialPostMetric[];

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

@@ -0,0 +1,51 @@
+import { getSocialCapabilityProfile, SOCIAL_POST_METRICS, } from "./social-capabilities.js";
+import { LINKEDIN_UNIPILE_POST_METRICS_PARSER_VERSION, linkedInUnipileMetricEvidence, parseLinkedInUnipilePostMetrics, } from "./social-post-metrics-linkedin.js";
+import { parseXComposioPostMetrics, X_COMPOSIO_POST_METRICS_PARSER_VERSION, xComposioMetricEvidence, } from "./social-post-metrics-x.js";
+const POST_METRICS_PARSERS = {
+    "linkedin:unipile": {
+        version: LINKEDIN_UNIPILE_POST_METRICS_PARSER_VERSION,
+        parse: parseLinkedInUnipilePostMetrics,
+        evidence: linkedInUnipileMetricEvidence,
+    },
+    "x:composio": {
+        version: X_COMPOSIO_POST_METRICS_PARSER_VERSION,
+        parse: parseXComposioPostMetrics,
+        evidence: xComposioMetricEvidence,
+    },
+};
+function parserFor(channel, providerRail) {
+    return POST_METRICS_PARSERS[`${channel}:${providerRail}`] ?? null;
+}
+/** Null when no parser is registered for the pair. */
+export function parseSocialPostMetrics(input) {
+    return parserFor(input.channel, input.providerRail)?.parse(input.payload) ?? null;
+}
+export function socialPostMetricsParserVersion(channel, providerRail) {
+    return parserFor(channel, providerRail)?.version ?? null;
+}
+/**
+ * The metric-bearing subset of a payload, stored with each observation so a
+ * parser fix can re-derive it without keeping post text, authors or media.
+ * Unknown pairs keep nothing.
+ */
+export function socialPostMetricEvidence(input) {
+    return parserFor(input.channel, input.providerRail)?.evidence(input.payload) ?? {};
+}
+/** Every registered (channel, provider rail) pair with its current parser version. */
+export function listSocialPostMetricsParsers() {
+    return Object.entries(POST_METRICS_PARSERS).map(([key, parser]) => {
+        const [channel, providerRail] = key.split(":");
+        return { channel, providerRail, version: parser.version };
+    });
+}
+/**
+ * Metrics the registry declares fully `available` for the pair that a parse did
+ * not produce. A non-empty answer on a real provider read is parser drift — the
+ * failure that silently stored every LinkedIn metric as NULL twice.
+ */
+export function missingDeclaredPostMetrics(input) {
+    const profile = getSocialCapabilityProfile(input.channel, input.providerRail);
+    if (!profile)
+        return [];
+    return SOCIAL_POST_METRICS.filter((metric) => profile.metrics[metric].status === "available" && input.parsed.metrics[metric] === undefined);
+}

package/node_modules/@oxygen/shared/dist/stripe-price-catalog.d.ts

@@ -0,0 +1,36 @@
+import { CONTACT_SALES_URL, PURCHASABLE_PLAN_KEYS, SELF_SERVE_PLAN_TIERS, normalizeBillingCurrency, type BillingCurrency, type OxygenPlanKey, type PricingPlanDefinition, type SelfServePlanTier } from "./billing.js";
+export { CONTACT_SALES_URL, PURCHASABLE_PLAN_KEYS, SELF_SERVE_PLAN_TIERS, normalizeBillingCurrency, };
+export type { BillingCurrency, OxygenPlanKey, SelfServePlanTier };
+export type PricingPlan = PricingPlanDefinition & {
+    priceIds: Record<BillingCurrency, string>;
+    priceId: string;
+};
+export declare const PRICING_PLANS: {
+    readonly free: PricingPlan;
+    readonly oxygen: PricingPlan;
+    readonly starter: PricingPlan;
+    readonly pro: PricingPlan;
+    readonly team: PricingPlan;
+    readonly scale: PricingPlan;
+    readonly enterprise: PricingPlan;
+};
+/** The six purchasable rungs with their Stripe price ids, cheapest first. */
+export declare const PURCHASABLE_PLANS: Record<OxygenPlanKey, PricingPlan>;
+export declare function getPlanPriceId(plan: PricingPlan, currency: BillingCurrency): string;
+/**
+ * Resolve a Stripe price id to the plan key stored in `subscriptions.tier`.
+ *
+ * Returns a plan KEY ("oxygen_499") for the six purchasable rungs and a TIER
+ * ("starter", "growth_250") for grandfathered plans. Both are resolvable by
+ * resolveBasePricingPlan, which is what the credit grant reads — so the rung a
+ * customer paid for is the allowance they receive.
+ */
+export declare function tierFromPriceId(priceId: string): string | null;
+/**
+ * Complete runtime-recognized Price set grouped by the current self-serve
+ * family. Catalog audit/migration code consumes this instead of maintaining a
+ * second env map that can silently omit grandfathered subscriptions.
+ */
+export declare function recognizedStripePriceIdsBySelfServeTier(): Record<SelfServePlanTier, readonly string[]>;
+export declare function formatMonthlyPrice(priceCents: number | null, currency?: BillingCurrency): string;
+export declare function getMonthlyAllowanceLabel(plan: PricingPlanDefinition): string;

package/node_modules/@oxygen/shared/dist/stripe-price-catalog.js

@@ -0,0 +1,184 @@
+import { BASE_PRICING_PLANS, CONTACT_SALES_URL, DEFAULT_BILLING_CURRENCY, PURCHASABLE_PLAN_KEYS, SELF_SERVE_PLAN_TIERS, normalizeBillingCurrency, resolveBasePricingPlan, } from "./billing.js";
+export { CONTACT_SALES_URL, PURCHASABLE_PLAN_KEYS, SELF_SERVE_PLAN_TIERS, normalizeBillingCurrency, };
+const EMPTY_PRICE_IDS = { usd: "" };
+/**
+ * The six purchasable Oxygen rungs: one Stripe Product EACH, one monthly
+ * Price on each. They cannot share a Product -- a Billing Portal configuration
+ * refuses two Prices of the same interval under one Product, which is what
+ * makes the plan picker configurable at all.
+ *
+ * These are consulted BEFORE the grandfathered maps in tierFromPriceId: if an
+ * Oxygen price id were ever also listed in a legacy env var, the legacy branch
+ * winning would grant a $499 customer a $99 plan's credits.
+ */
+const STRIPE_PRICE_OXYGEN_IDS = {
+    oxygen_49: { usd: process.env.STRIPE_PRICE_OXYGEN_49_USD ?? "" },
+    oxygen_99: { usd: process.env.STRIPE_PRICE_OXYGEN_99_USD ?? "" },
+    oxygen_199: { usd: process.env.STRIPE_PRICE_OXYGEN_199_USD ?? "" },
+    oxygen_499: { usd: process.env.STRIPE_PRICE_OXYGEN_499_USD ?? "" },
+    oxygen_999: { usd: process.env.STRIPE_PRICE_OXYGEN_999_USD ?? "" },
+    oxygen_1999: { usd: process.env.STRIPE_PRICE_OXYGEN_1999_USD ?? "" },
+};
+// Grandfathered on 2026-09-19. These three stay pointed at their LIVE prices
+// (35 Starter + 2 Pro subscriptions bill against them) rather than moving into
+// the legacy CSV lists: tierFromPriceId must keep returning "starter"/"pro"/
+// "team" for them so resolveBasePricingPlan yields the plan those customers
+// actually bought. They are simply no longer offered for sale.
+const STRIPE_PRICE_STARTER_IDS = {
+    usd: process.env.STRIPE_PRICE_STARTER_99_USD ?? "",
+};
+const STRIPE_PRICE_PRO_IDS = {
+    usd: process.env.STRIPE_PRICE_PRO_249_USD ?? "",
+};
+const STRIPE_PRICE_TEAM_IDS = {
+    usd: process.env.STRIPE_PRICE_TEAM_749_USD ?? "",
+};
+const LEGACY_STRIPE_PRICE_IDS = {
+    starter_50: {
+        usd: process.env.STRIPE_PRICE_STARTER_USD ?? "",
+    },
+    pro_149: {
+        usd: process.env.STRIPE_PRICE_PRO_USD ?? "",
+    },
+    team_399: {
+        usd: process.env.STRIPE_PRICE_TEAM_USD ?? "",
+    },
+};
+const LEGACY_CURRENT_PLAN_PRICE_IDS = {
+    oxygen: readCommaSeparatedPriceIds(process.env.STRIPE_LEGACY_PRICE_OXYGEN_IDS),
+    starter: readCommaSeparatedPriceIds(process.env.STRIPE_LEGACY_PRICE_STARTER_IDS),
+    pro: readCommaSeparatedPriceIds(process.env.STRIPE_LEGACY_PRICE_PRO_IDS),
+    team: readCommaSeparatedPriceIds(process.env.STRIPE_LEGACY_PRICE_TEAM_IDS),
+};
+const SELF_SERVE_TIER_BY_LEGACY_TIER = {
+    starter_50: "starter",
+    pro_149: "pro",
+    team_399: "team",
+};
+function withPriceIds(plan, priceIds = EMPTY_PRICE_IDS) {
+    return {
+        ...plan,
+        priceIds,
+        priceId: priceIds[DEFAULT_BILLING_CURRENCY],
+    };
+}
+export const PRICING_PLANS = {
+    free: withPriceIds(BASE_PRICING_PLANS.free),
+    oxygen: withPriceIds(BASE_PRICING_PLANS.oxygen, STRIPE_PRICE_OXYGEN_IDS.oxygen_49),
+    starter: withPriceIds(BASE_PRICING_PLANS.starter, STRIPE_PRICE_STARTER_IDS),
+    pro: withPriceIds(BASE_PRICING_PLANS.pro, STRIPE_PRICE_PRO_IDS),
+    team: withPriceIds(BASE_PRICING_PLANS.team, STRIPE_PRICE_TEAM_IDS),
+    scale: withPriceIds(BASE_PRICING_PLANS.scale),
+    enterprise: withPriceIds(BASE_PRICING_PLANS.enterprise),
+};
+/** The six purchasable rungs with their Stripe price ids, cheapest first. */
+export const PURCHASABLE_PLANS = Object.fromEntries(PURCHASABLE_PLAN_KEYS.map((planKey) => {
+    const plan = resolveBasePricingPlan(planKey);
+    if (!plan)
+        throw new Error(`purchasable plan "${planKey}" is missing from the catalog`);
+    return [planKey, withPriceIds(plan, STRIPE_PRICE_OXYGEN_IDS[planKey])];
+}));
+export function getPlanPriceId(plan, currency) {
+    return (plan.priceIds[currency]
+        || (currency === DEFAULT_BILLING_CURRENCY ? plan.priceId : ""));
+}
+/**
+ * Resolve a Stripe price id to the plan key stored in `subscriptions.tier`.
+ *
+ * Returns a plan KEY ("oxygen_499") for the six purchasable rungs and a TIER
+ * ("starter", "growth_250") for grandfathered plans. Both are resolvable by
+ * resolveBasePricingPlan, which is what the credit grant reads — so the rung a
+ * customer paid for is the allowance they receive.
+ */
+export function tierFromPriceId(priceId) {
+    // An absent/unset Stripe price is "" on every map below (each env read falls
+    // back to ""), so without this guard an empty id matches the FIRST unset rung
+    // and silently provisions a paid plan. Never resolve a tier from no price.
+    if (!priceId)
+        return null;
+    for (const planKey of PURCHASABLE_PLAN_KEYS) {
+        if (Object.values(STRIPE_PRICE_OXYGEN_IDS[planKey]).includes(priceId)) {
+            return planKey;
+        }
+    }
+    for (const tier of SELF_SERVE_PLAN_TIERS) {
+        const plan = PRICING_PLANS[tier];
+        if (plan.priceId === priceId
+            || Object.values(plan.priceIds).includes(priceId)) {
+            return tier;
+        }
+    }
+    for (const [tier, priceIds] of Object.entries(LEGACY_STRIPE_PRICE_IDS)) {
+        if (Object.values(priceIds).includes(priceId))
+            return tier;
+    }
+    for (const [tier, priceIds] of Object.entries(LEGACY_CURRENT_PLAN_PRICE_IDS)) {
+        if (priceIds.includes(priceId))
+            return tier;
+    }
+    return null;
+}
+/**
+ * Complete runtime-recognized Price set grouped by the current self-serve
+ * family. Catalog audit/migration code consumes this instead of maintaining a
+ * second env map that can silently omit grandfathered subscriptions.
+ */
+export function recognizedStripePriceIdsBySelfServeTier() {
+    const byTier = {
+        oxygen: [
+            ...PURCHASABLE_PLAN_KEYS.flatMap((planKey) => Object.values(STRIPE_PRICE_OXYGEN_IDS[planKey])),
+            ...LEGACY_CURRENT_PLAN_PRICE_IDS.oxygen,
+        ],
+        starter: [
+            ...Object.values(STRIPE_PRICE_STARTER_IDS),
+            ...LEGACY_CURRENT_PLAN_PRICE_IDS.starter,
+        ],
+        pro: [
+            ...Object.values(STRIPE_PRICE_PRO_IDS),
+            ...LEGACY_CURRENT_PLAN_PRICE_IDS.pro,
+        ],
+        team: [
+            ...Object.values(STRIPE_PRICE_TEAM_IDS),
+            ...LEGACY_CURRENT_PLAN_PRICE_IDS.team,
+        ],
+    };
+    for (const legacyTier of Object.keys(LEGACY_STRIPE_PRICE_IDS)) {
+        byTier[SELF_SERVE_TIER_BY_LEGACY_TIER[legacyTier]]
+            .push(...Object.values(LEGACY_STRIPE_PRICE_IDS[legacyTier]));
+    }
+    return {
+        oxygen: uniqueNonEmptyPriceIds(byTier.oxygen),
+        starter: uniqueNonEmptyPriceIds(byTier.starter),
+        pro: uniqueNonEmptyPriceIds(byTier.pro),
+        team: uniqueNonEmptyPriceIds(byTier.team),
+    };
+}
+function readCommaSeparatedPriceIds(value) {
+    if (!value)
+        return [];
+    return [...new Set(value.split(",").map((entry) => entry.trim()).filter(Boolean))];
+}
+function uniqueNonEmptyPriceIds(values) {
+    return [...new Set(values.map((entry) => entry.trim()).filter(Boolean))];
+}
+export function formatMonthlyPrice(priceCents, currency = DEFAULT_BILLING_CURRENCY) {
+    if (priceCents == null)
+        return "Custom";
+    if (priceCents === 0)
+        return "Free";
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        maximumFractionDigits: 0,
+    }).format(priceCents / 100);
+}
+function formatCredits(credits) {
+    if (credits == null)
+        return "Custom credits";
+    return `${new Intl.NumberFormat("en-US").format(credits)} credits`;
+}
+export function getMonthlyAllowanceLabel(plan) {
+    if (plan.monthlyCredits == null)
+        return "Custom monthly credits";
+    return `${formatCredits(plan.monthlyCredits)} / month`;
+}

package/node_modules/@oxygen/shared/dist/stripe-subscription-kind.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which Stripe subscriptions are NOT an OXYGEN plan.
+ *
+ * OXYGEN runs three recurring rails on the same Stripe customer, and only one of
+ * them is a plan: the PLAN subscription (born from a Checkout Session),
+ * EMAIL INFRASTRUCTURE (`infra-subscription.ts`) and SENDING SEATS
+ * (`seat-subscription.ts`). The two rails are separate on purpose — a workspace
+ * with no plan at all must be able to hold managed inboxes and buy a sending
+ * seat — so a rail event is not a smaller version of a plan event, it is a
+ * different subject entirely, and plan-shaped handling of one is always wrong.
+ *
+ * THE WITNESS IS `metadata.oxygen_kind`. Both rails stamp it at
+ * `subscriptions.create` (the only two such call sites in the repo), and a plan
+ * subscription never carries it: a plan is born from a Checkout Session whose
+ * `subscription_data.metadata` carries organization_id/clerk_org_id and no
+ * `oxygen_kind`. (The third `oxygen_kind` in the codebase, `credit_topup`, rides
+ * a one-off `mode: "payment"` Checkout Session and never produces a
+ * subscription at all.) So the key's PRESENCE is a positive witness of "not a
+ * plan".
+ *
+ * PRESENCE, NOT A VALUE LIST, deliberately. Every previous gate matched the one
+ * value `"email_infra"`, which is why the seat rail — shipped later — walked
+ * straight into the plan handlers: adding a rail silently opted it INTO plan
+ * treatment, the wrong default for a safety gate. Testing presence means the
+ * next rail needs no edit here. This is the same reasoning `orphan-reconcile.ts`
+ * measured in production on 2026-09-06, where all 24 of the 24 daily
+ * `billing.subscription_health.unknown_plan_price` error lines were the same 4
+ * live sending-seat subscriptions x 6 cron runs.
+ *
+ * DELIBERATELY NARROW. This answers "did the subscription declare itself a
+ * non-plan rail", never "does it carry a recognised plan price". The catalog
+ * question stays with `tierFromPriceId` / `recognizedStripePlanItems`, and
+ * callers that need both keep asking both — `orphan-reconcile.ts` reclassifies
+ * only the zero-recognised-item half for exactly that reason.
+ */
+type StripeSubscriptionMetadata = Readonly<Record<string, string | null | undefined>> | null | undefined;
+/** The declared non-plan rail (`email_infra`, `sending_seats`, …), or null for a plan. */
+export declare function nonPlanSubscriptionKind(metadata: StripeSubscriptionMetadata): string | null;
+/** True when the subscription declared itself one of OXYGEN's non-plan rails. */
+export declare function isNonPlanSubscriptionKind(metadata: StripeSubscriptionMetadata): boolean;
+export {};