@peasant-labs/fairtrade 0.0.2 → 0.0.4

package/dist/lib/types/analytics/types.d.ts

@@ -0,0 +1,453 @@
+/**
+ * How a recorded session ended.
+ * @typedef {'resolved' | 'partial' | 'failed'} AnalyticsSessionOutcome
+ */
+/** Canonical AnalyticsSessionOutcome values. @type {readonly AnalyticsSessionOutcome[]} */
+export const ANALYTICS_SESSION_OUTCOMES: readonly AnalyticsSessionOutcome[];
+/**
+ * One recorded agent session, as the analytics dashboard consumes it. This is
+ * the fairtrade-owned record shape — apps map their own wire types onto it.
+ * Only the fields the dashboard actually reads are part of the contract.
+ * @typedef {object} AnalyticsSessionRecord
+ * @property {string} [id] Stable session id (not read by the dashboard; kept
+ *   for adapter round-tripping and keying host-side lists).
+ * @property {string} startTime ISO-8601 timestamp; all week/day bucketing is
+ *   done in UTC against this.
+ * @property {string} projectKey Opaque project key (repo, collective, …).
+ * @property {string} contributorId Opaque contributor key; empty ids are
+ *   skipped by the contributor metrics.
+ * @property {number} durationMins Session duration in minutes.
+ * @property {number} totalTokens Total tokens across the session.
+ * @property {number} turnCount Conversation turns.
+ * @property {number} toolCallCount Tool invocations.
+ * @property {AnalyticsSessionOutcome} [outcome] Unset buckets as "unknown".
+ * @property {boolean} [hasCommit] Fallback commit flag when `commitCount` is
+ *   absent.
+ * @property {number} [commitCount] Preferred commit linkage; `> 0` wins over
+ *   `hasCommit`.
+ */
+/**
+ * One bucket of the per-week session-count series (`week` = Monday-of-week UTC
+ * date key, `YYYY-MM-DD`).
+ * @typedef {object} WeekCount
+ * @property {string} week
+ * @property {number} count
+ */
+/**
+ * One bucket of the per-week unique-contributor series.
+ * @typedef {object} WeekContributors
+ * @property {string} week
+ * @property {number} contributors Distinct contributor ids active that week.
+ */
+/**
+ * Result of the returning-contributor calculation.
+ * @typedef {object} ReturningContributorRate
+ * @property {number} total Distinct contributors with ≥1 session.
+ * @property {number} returning Distinct contributors active in ≥2 distinct weeks.
+ * @property {number} rate returning / total, in [0, 1]; 0 when no contributors.
+ */
+/**
+ * Result of a streak calculation.
+ * @typedef {object} LongestStreak
+ * @property {number} weeks Length of the longest run of consecutive active weeks.
+ * @property {string | null} startWeek First Monday-key of that run, or null.
+ * @property {string | null} endWeek Last Monday-key of that run, or null.
+ */
+/**
+ * One bucket of the new-contributor series.
+ * @typedef {object} WeekNewContributors
+ * @property {string} week
+ * @property {number} newContributors Contributors whose FIRST-EVER session
+ *   falls in this week.
+ */
+/**
+ * Result of the session→commit calculation.
+ * @typedef {object} SessionToCommitRate
+ * @property {number} total Total sessions considered.
+ * @property {number} withCommit Sessions that produced ≥1 commit.
+ * @property {number} rate withCommit / total, in [0, 1]; 0 when no sessions.
+ */
+/**
+ * One bucket of the per-active-week average-duration series.
+ * @typedef {object} WeekAvgDuration
+ * @property {string} week
+ * @property {number} avgDurationMins Mean session duration (minutes) that week.
+ * @property {number} sessions Number of sessions that fed the average.
+ */
+/**
+ * Distribution of session outcomes; the four buckets always sum to `total`
+ * (sessions with no `outcome` bucket under `unknown`).
+ * @typedef {object} OutcomeDistribution
+ * @property {number} resolved
+ * @property {number} partial
+ * @property {number} failed
+ * @property {number} unknown
+ * @property {number} total
+ */
+/**
+ * Median + 90th-percentile pair for a numeric distribution.
+ * @typedef {object} MedianP90
+ * @property {number} count Number of (finite) samples that fed the statistic.
+ * @property {number | null} median 50th percentile; null for an empty input.
+ * @property {number | null} p90 90th percentile; null for an empty input.
+ */
+/**
+ * Median + p90 for the four core numeric session fields ("typical vs. tail").
+ * @typedef {object} SessionStats
+ * @property {MedianP90} durationMins
+ * @property {MedianP90} totalTokens
+ * @property {MedianP90} turnCount
+ * @property {MedianP90} toolCallCount
+ */
+/**
+ * Per-contributor rolled-up summary (one contributor-table row).
+ * @typedef {object} ContributorBreakdown
+ * @property {string} contributorId
+ * @property {number} sessions Total sessions by this contributor.
+ * @property {number} activeWeeks Distinct ISO weeks this contributor was active.
+ * @property {number} totalTokens
+ * @property {number} totalDurationMins
+ * @property {number} totalTurns
+ * @property {number} totalToolCalls
+ * @property {number} sessionsWithCommit Sessions that produced ≥1 commit.
+ * @property {number} totalCommits Total linked commits (sum of `commitCount`;
+ *   a session carrying only `hasCommit: true` counts as 1, so this is a lower
+ *   bound when the host exposes the flag but not the count).
+ * @property {OutcomeDistribution} outcomes Outcome tally for this contributor.
+ * @property {string | null} firstSeen Earliest session day-key (`YYYY-MM-DD`).
+ * @property {string | null} lastSeen Latest session day-key (`YYYY-MM-DD`).
+ */
+/**
+ * The fully-computed analytics bundle. `ProjectOverview` accepts either this
+ * (pre-computed by the host) or raw `AnalyticsSessionRecord[]` it computes
+ * itself via `computeProjectAnalytics`.
+ * @typedef {object} ProjectAnalytics
+ * @property {number} totalSessions Distinct sessions considered.
+ * @property {number} totalContributors Distinct contributors.
+ * @property {number} totalProjects Distinct projects (`projectKey` values).
+ * @property {WeekCount[]} sessionsPerWeek
+ * @property {WeekContributors[]} weeklyActiveContributors
+ * @property {ReturningContributorRate} returningContributorRate
+ * @property {LongestStreak} longestStreak
+ * @property {WeekNewContributors[]} newContributorVelocity
+ * @property {SessionToCommitRate} sessionToCommitRate
+ * @property {WeekAvgDuration[]} avgDurationPerActiveWeek
+ * @property {OutcomeDistribution} outcomeDistribution
+ * @property {SessionStats} sessionStats
+ * @property {ContributorBreakdown[]} perContributorBreakdown
+ */
+/**
+ * The cooked payload `<ProjectOverview payload={…}>` consumes. Provide exactly
+ * one of the two fields; `analytics` wins when both are given.
+ * @typedef {object} AnalyticsOverviewPayload
+ * @property {AnalyticsSessionRecord[]} [sessions] Raw path — the surface
+ *   computes every metric itself.
+ * @property {ProjectAnalytics} [analytics] Pre-computed path (host computed
+ *   the bundle, e.g. server-side).
+ */
+/**
+ * The dashboard's toggleable sections.
+ * @typedef {'summary' | 'sessionsPerWeek' | 'weeklyActiveContributors'
+ *   | 'newContributorVelocity' | 'avgDurationPerActiveWeek'
+ *   | 'outcomeDistribution' | 'sessionStats' | 'contributorTable'
+ * } ProjectOverviewSectionKey
+ */
+/**
+ * The dashboard's sections: canonical keys paired with their visible chip
+ * labels, in render order. Single source of truth — the KEYS array below and
+ * the component's chip row both derive from this, so key set, order and
+ * labels cannot drift apart.
+ * @type {ReadonlyArray<{ key: ProjectOverviewSectionKey, label: string }>}
+ */
+export const PROJECT_OVERVIEW_SECTION_DEFS: ReadonlyArray<{
+    key: ProjectOverviewSectionKey;
+    label: string;
+}>;
+/** Canonical section keys, in render order (derived). @type {readonly ProjectOverviewSectionKey[]} */
+export const PROJECT_OVERVIEW_SECTION_KEYS: readonly ProjectOverviewSectionKey[];
+/**
+ * How a recorded session ended.
+ */
+export type AnalyticsSessionOutcome = "resolved" | "partial" | "failed";
+/**
+ * One recorded agent session, as the analytics dashboard consumes it. This is
+ * the fairtrade-owned record shape — apps map their own wire types onto it.
+ * Only the fields the dashboard actually reads are part of the contract.
+ */
+export type AnalyticsSessionRecord = {
+    /**
+     * Stable session id (not read by the dashboard; kept
+     * for adapter round-tripping and keying host-side lists).
+     */
+    id?: string;
+    /**
+     * ISO-8601 timestamp; all week/day bucketing is
+     * done in UTC against this.
+     */
+    startTime: string;
+    /**
+     * Opaque project key (repo, collective, …).
+     */
+    projectKey: string;
+    /**
+     * Opaque contributor key; empty ids are
+     * skipped by the contributor metrics.
+     */
+    contributorId: string;
+    /**
+     * Session duration in minutes.
+     */
+    durationMins: number;
+    /**
+     * Total tokens across the session.
+     */
+    totalTokens: number;
+    /**
+     * Conversation turns.
+     */
+    turnCount: number;
+    /**
+     * Tool invocations.
+     */
+    toolCallCount: number;
+    /**
+     * Unset buckets as "unknown".
+     */
+    outcome?: AnalyticsSessionOutcome;
+    /**
+     * Fallback commit flag when `commitCount` is
+     * absent.
+     */
+    hasCommit?: boolean;
+    /**
+     * Preferred commit linkage; `> 0` wins over
+     * `hasCommit`.
+     */
+    commitCount?: number;
+};
+/**
+ * One bucket of the per-week session-count series (`week` = Monday-of-week UTC
+ * date key, `YYYY-MM-DD`).
+ */
+export type WeekCount = {
+    week: string;
+    count: number;
+};
+/**
+ * One bucket of the per-week unique-contributor series.
+ */
+export type WeekContributors = {
+    week: string;
+    /**
+     * Distinct contributor ids active that week.
+     */
+    contributors: number;
+};
+/**
+ * Result of the returning-contributor calculation.
+ */
+export type ReturningContributorRate = {
+    /**
+     * Distinct contributors with ≥1 session.
+     */
+    total: number;
+    /**
+     * Distinct contributors active in ≥2 distinct weeks.
+     */
+    returning: number;
+    /**
+     * returning / total, in [0, 1]; 0 when no contributors.
+     */
+    rate: number;
+};
+/**
+ * Result of a streak calculation.
+ */
+export type LongestStreak = {
+    /**
+     * Length of the longest run of consecutive active weeks.
+     */
+    weeks: number;
+    /**
+     * First Monday-key of that run, or null.
+     */
+    startWeek: string | null;
+    /**
+     * Last Monday-key of that run, or null.
+     */
+    endWeek: string | null;
+};
+/**
+ * One bucket of the new-contributor series.
+ */
+export type WeekNewContributors = {
+    week: string;
+    /**
+     * Contributors whose FIRST-EVER session
+     * falls in this week.
+     */
+    newContributors: number;
+};
+/**
+ * Result of the session→commit calculation.
+ */
+export type SessionToCommitRate = {
+    /**
+     * Total sessions considered.
+     */
+    total: number;
+    /**
+     * Sessions that produced ≥1 commit.
+     */
+    withCommit: number;
+    /**
+     * withCommit / total, in [0, 1]; 0 when no sessions.
+     */
+    rate: number;
+};
+/**
+ * One bucket of the per-active-week average-duration series.
+ */
+export type WeekAvgDuration = {
+    week: string;
+    /**
+     * Mean session duration (minutes) that week.
+     */
+    avgDurationMins: number;
+    /**
+     * Number of sessions that fed the average.
+     */
+    sessions: number;
+};
+/**
+ * Distribution of session outcomes; the four buckets always sum to `total`
+ * (sessions with no `outcome` bucket under `unknown`).
+ */
+export type OutcomeDistribution = {
+    resolved: number;
+    partial: number;
+    failed: number;
+    unknown: number;
+    total: number;
+};
+/**
+ * Median + 90th-percentile pair for a numeric distribution.
+ */
+export type MedianP90 = {
+    /**
+     * Number of (finite) samples that fed the statistic.
+     */
+    count: number;
+    /**
+     * 50th percentile; null for an empty input.
+     */
+    median: number | null;
+    /**
+     * 90th percentile; null for an empty input.
+     */
+    p90: number | null;
+};
+/**
+ * Median + p90 for the four core numeric session fields ("typical vs. tail").
+ */
+export type SessionStats = {
+    durationMins: MedianP90;
+    totalTokens: MedianP90;
+    turnCount: MedianP90;
+    toolCallCount: MedianP90;
+};
+/**
+ * Per-contributor rolled-up summary (one contributor-table row).
+ */
+export type ContributorBreakdown = {
+    contributorId: string;
+    /**
+     * Total sessions by this contributor.
+     */
+    sessions: number;
+    /**
+     * Distinct ISO weeks this contributor was active.
+     */
+    activeWeeks: number;
+    totalTokens: number;
+    totalDurationMins: number;
+    totalTurns: number;
+    totalToolCalls: number;
+    /**
+     * Sessions that produced ≥1 commit.
+     */
+    sessionsWithCommit: number;
+    /**
+     * Total linked commits (sum of `commitCount`;
+     * a session carrying only `hasCommit: true` counts as 1, so this is a lower
+     * bound when the host exposes the flag but not the count).
+     */
+    totalCommits: number;
+    /**
+     * Outcome tally for this contributor.
+     */
+    outcomes: OutcomeDistribution;
+    /**
+     * Earliest session day-key (`YYYY-MM-DD`).
+     */
+    firstSeen: string | null;
+    /**
+     * Latest session day-key (`YYYY-MM-DD`).
+     */
+    lastSeen: string | null;
+};
+/**
+ * The fully-computed analytics bundle. `ProjectOverview` accepts either this
+ * (pre-computed by the host) or raw `AnalyticsSessionRecord[]` it computes
+ * itself via `computeProjectAnalytics`.
+ */
+export type ProjectAnalytics = {
+    /**
+     * Distinct sessions considered.
+     */
+    totalSessions: number;
+    /**
+     * Distinct contributors.
+     */
+    totalContributors: number;
+    /**
+     * Distinct projects (`projectKey` values).
+     */
+    totalProjects: number;
+    sessionsPerWeek: WeekCount[];
+    weeklyActiveContributors: WeekContributors[];
+    returningContributorRate: ReturningContributorRate;
+    longestStreak: LongestStreak;
+    newContributorVelocity: WeekNewContributors[];
+    sessionToCommitRate: SessionToCommitRate;
+    avgDurationPerActiveWeek: WeekAvgDuration[];
+    outcomeDistribution: OutcomeDistribution;
+    sessionStats: SessionStats;
+    perContributorBreakdown: ContributorBreakdown[];
+};
+/**
+ * The cooked payload `<ProjectOverview payload={…}>` consumes. Provide exactly
+ * one of the two fields; `analytics` wins when both are given.
+ */
+export type AnalyticsOverviewPayload = {
+    /**
+     * Raw path — the surface
+     * computes every metric itself.
+     */
+    sessions?: AnalyticsSessionRecord[];
+    /**
+     * Pre-computed path (host computed
+     * the bundle, e.g. server-side).
+     */
+    analytics?: ProjectAnalytics;
+};
+/**
+ * The dashboard's toggleable sections.
+ */
+export type ProjectOverviewSectionKey = "summary" | "sessionsPerWeek" | "weeklyActiveContributors" | "newContributorVelocity" | "avgDurationPerActiveWeek" | "outcomeDistribution" | "sessionStats" | "contributorTable";
+/**
+ * Host-level section visibility. Every flag defaults to ON; set one to `false`
+ * to hide that section. The built-in visible-section control can hide sections
+ * at runtime, but it cannot re-enable a host-hidden section.
+ */
+export type ProjectOverviewSections = Partial<Record<ProjectOverviewSectionKey, boolean>>;

package/dist/lib/types/commons/Explore.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @typedef {import('./types.js').ExploreSurfaceProps} ExploreSurfaceProps
+ */
+/** @param {ExploreSurfaceProps} props */
+export default function Explore({ data, className, onFiltersChange, onOpenTranscript, onOpenProfile, onOpenCollective, transcriptHref, profileHref, collectiveHref, }: ExploreSurfaceProps): any;
+export type ExploreSurfaceProps = import("./types.js").ExploreSurfaceProps;

package/dist/lib/types/commons/Manage.d.ts

@@ -0,0 +1,34 @@
+export function Manage({ data, actions, demoRoleSwitcher, }?: {
+    data?: {
+        collective: {
+            name: string;
+            description: any;
+            linkedGithubOrg: any;
+            acceptanceMode: string;
+            dataAccess: string;
+            role: string;
+            memberSince: any;
+        };
+        providerShare: any[];
+        pendingReview: any[];
+        members: any[];
+        redactions: any[];
+        browseRows: any[];
+        roleOptions: any[];
+        initialRole: string;
+        initialShowRedaction: boolean;
+        initialBrowseGated: boolean;
+        stats: {
+            transcripts: string;
+            projects: string;
+            tokens: string;
+            turns: string;
+            contributors: string;
+            hours: string;
+        };
+    };
+    actions?: {};
+    demoRoleSwitcher?: boolean;
+}): any;
+export { PROVIDER_LABEL, formatProvider, providerLabel } from "./providers.js";
+export { PublishView, CollectivesView, CollectiveDetailView, CollectiveSettingsView, ContributeView } from "../../mockups/inuse/CommonsManage.jsx";

package/dist/lib/types/commons/index.d.ts

@@ -0,0 +1,24 @@
+export { default as Explore } from "./Explore.jsx";
+export type TranscriptVisibility = import("./types.js").TranscriptVisibility;
+export type AcceptanceMode = import("./types.js").AcceptanceMode;
+export type DataAccessPolicy = import("./types.js").DataAccessPolicy;
+export type TranscriptDeletionPolicy = import("./types.js").TranscriptDeletionPolicy;
+export type CollectiveRole = import("./types.js").CollectiveRole;
+export type ViewerRole = import("./types.js").ViewerRole;
+export type ExploreSurfaceProps = import("./types.js").ExploreSurfaceProps;
+export type TagPayload = import("./types.js").TagPayload;
+export type ExploreOwnerPayload = import("./types.js").ExploreOwnerPayload;
+export type ExploreTranscriptPayload = import("./types.js").ExploreTranscriptPayload;
+export type ExploreTranscriptListPayload = import("./types.js").ExploreTranscriptListPayload;
+export type CollectiveResultPayload = import("./types.js").CollectiveResultPayload;
+export type PopularTagPayload = import("./types.js").PopularTagPayload;
+export type ExplorePayload = import("./types.js").ExplorePayload;
+export type CollectiveMemberPayload = import("./types.js").CollectiveMemberPayload;
+export type CollectiveTranscriptPayload = import("./types.js").CollectiveTranscriptPayload;
+export type CollectiveStatsPayload = import("./types.js").CollectiveStatsPayload;
+export type CollectiveModelBreakdownPayload = import("./types.js").CollectiveModelBreakdownPayload;
+export type CollectiveContributorPayload = import("./types.js").CollectiveContributorPayload;
+export type CollectivePayload = import("./types.js").CollectivePayload;
+export type ManagePayload = import("./types.js").ManagePayload;
+export { TRANSCRIPT_VISIBILITIES, ACCEPTANCE_MODES, DATA_ACCESS_POLICIES, TRANSCRIPT_DELETION_POLICIES, COLLECTIVE_ROLES } from "./types.js";
+export { Manage, PublishView, CollectivesView, CollectiveDetailView, CollectiveSettingsView, ContributeView } from "./Manage.jsx";

package/dist/lib/types/commons/providers.d.ts

@@ -0,0 +1,8 @@
+export function formatProvider(provider: any): string;
+export function providerLabel(provider: any): any;
+export const PROVIDER_LABEL: {
+    'claude-code': string;
+    'gemini-cli': string;
+    opencode: string;
+    codex: string;
+};