RevenueFlow.Analytics
0.1.0-alpha.7.2
dotnet add package RevenueFlow.Analytics --version 0.1.0-alpha.7.2
NuGet\Install-Package RevenueFlow.Analytics -Version 0.1.0-alpha.7.2
<PackageReference Include="RevenueFlow.Analytics" Version="0.1.0-alpha.7.2" />
<PackageVersion Include="RevenueFlow.Analytics" Version="0.1.0-alpha.7.2" />
<PackageReference Include="RevenueFlow.Analytics" />
paket add RevenueFlow.Analytics --version 0.1.0-alpha.7.2
#r "nuget: RevenueFlow.Analytics, 0.1.0-alpha.7.2"
#:package RevenueFlow.Analytics@0.1.0-alpha.7.2
#addin nuget:?package=RevenueFlow.Analytics&version=0.1.0-alpha.7.2&prerelease
#tool nuget:?package=RevenueFlow.Analytics&version=0.1.0-alpha.7.2&prerelease
RevenueFlow.Analytics
Optional committed-event projection, currency-separated observed revenue/cohort/subscription reports and resumable scheduled CSV/JSONL exports. Core owns replaceable reader/export/sink contracts. Source IDs and command receipts deduplicate delivery; reporting never changes commerce effects. No implicit exchange-rate, tax or accounting adjustment is invented. Exports preserve source row IDs for downstream deduplication; late history can be explicitly re-exported. Sinks must deduplicate scoped batch IDs and fingerprints. The file sink is a working reference, and WalFlow remains optional.
Independent storage roles
RevenueFlow.Stores.Abstractions.Analytics defines immutable typed fact ingestion, native reporting/pagination and generation maintenance. The regular RevenueFlow.Stores.Postgres package implements these roles with PostgresRevenueAnalyticsStore. Use the same application-owned NpgsqlDataSource as commerce or a separate database. Call PostgresRevenueAnalyticsSchema.InitializeAsync explicitly. Persistence packages choose their physical schema; reporting contracts impose no star/snowflake layout.
await PostgresRevenueAnalyticsSchema.InitializeAsync(analyticsDataSource, cancellationToken);
var analytics = new PostgresRevenueAnalyticsStore(analyticsDataSource);
await analytics.CreateGenerationAsync(scope, "v2", cancellationToken);
var projection = new RevenueAnalyticsService(
commerceDocuments, factWriter: analytics, queryStore: analytics, generation: "v2");
// Register projection.ConsumerId on commerce producers and dispatch/enroll retained history for it.
// Direct totals queries can inspect a generation before activation, without loading customer drilldowns.
var totals = await analytics.ReportTotalsAsync(scope, "v2", fromUtc, toUtc, cancellationToken);
Every native ingestion commits all financial, subscription, resource and growth facts with the source receipt before acknowledging delivery. Cross-database commit uncertainty retries through that receipt; it never joins the commerce transaction. Changed facts at an existing source identity fail. Line identities and subscription revisions additionally reject conflicting reuse across source events. First-observed financial recorded time remains stable on retries. Subscription metrics use trusted revisions rather than arrival order. New business events retain immutable order, adjustment and resource snapshots; PrepareTrustedBatchAsync can translate complete trusted snapshots without database access. That method does not authenticate event provenance: callers must establish trusted full scope and immutable source identity. HandleAsync verifies operational history first. Legacy incomplete events use retained source reads; legacy incoming transfer discovery remains bounded and fails explicitly if it cannot prove the complete transfer.
WriteManyAsync accepts 1–100 distinct source events from one full scope/generation, at most 256 resource facts per event and 1000 per microbatch. The native PostgreSQL implementation snapshots inputs, checks all immutable identities, then pipelines inserts through NpgsqlBatch in one transaction. A conflicting microbatch commits nothing. Native ingestion and external admission serialize briefly on the existing generation row; different app scopes and external destinations remain independent. Locks never span a ClickHouse HTTP request. Custom adapters' default bulk method retains per-event durability and must document any stronger microbatch guarantee.
For large audiences, use the optional IRevenueAnalyticsTotalsQueryStore.ReportTotalsAsync capability or Core IRevenueAnalyticsTotalsReader through RevenueNativeAnalyticsTotalsReader. The facade resolves the active generation. Totals return currency metrics and scalar subscription/observation counts; native queries skip customer, product, origin and cohort detail lists entirely. Lifetime customer cardinality therefore cannot exhaust a detailed-report result bound and prevent ordinary revenue totals. The only currency bound is the finite validated three-letter ASCII currency domain; currencies stay separate.
PostgreSQL reports filter and aggregate inside SQL under a repeatable-read snapshot. Monetary sums use decimal arithmetic. Native time comparisons preserve .NET UTC ticks, including 100 ns half-open range boundaries. The compatible detailed ReportAsync limits result groups, not underlying facts, and fails rather than silently truncating; its lifetime customer list makes it appropriate only for bounded detail workloads. Use ReadCustomerPageAsync for large customer drilldowns, ReadGrowthAsync for experiment measurements and stable native fact pages for exports. Exposure counts are per variant and repeat for each conversion currency; do not sum those repeated denominators across currencies. Current customer subscription/access decisions still use the transactional store. Historical active counts, MRR, trials and churn use analytical observations, which can lag commerce.
Without native writer/query roles, the original document-backed projection remains available. Its report discovers at most maximumRecords financial/subscription documents and fails when exceeded; this fallback is intended for bounded deployments.
Rebuilds and observed coverage
Create a new shadow generation and enroll RevenueAnalyticsService.ConsumerForGeneration(generation) through the existing event backfill/dispatch pipeline. Receipts are generation-specific, so replay never overwrites the active generation. An application must establish an independently complete source set and expected normalized facts, including late commits, then calculate RevenueAnalyticsManifest using ordered source IDs/fingerprints and RevenueAnalyticsFacts.Fingerprint for typed facts. RevenueAnalyticsFacts.Manifest computes each digest. The fact digest is generation-specific; build expected batches for the target generation.
ProjectHistoryPageAsync(scope, pageSize, afterId) is a working bulk replay bridge: it reads at most 100 scoped retained events, verifies their schemas/identities and builds immutable facts. It automatically splits resource-heavy pages into native WriteManyAsync chunks of at most 100 events and 1000 resource facts. The page cursor is returned only after every chunk is acknowledged; retry the same previous cursor after an uncertain response, including chunks already accepted. Immutable source receipts deduplicate those retries. It rejects missing native writer configuration. Legacy mapping retains its explicit discovery bounds. Concurrent/late history still requires the independently complete source capture above; reaching the end of live UUID pagination proves only that scan's observed coverage.
SealAsync takes both expected digests and source count, serializes against ingestion and freezes the shadow only if they match. ActivateAsync compares the expected active generation and atomically switches readers, reopening the new generation for ingestion. Retired generations reject additional facts and require a fresh reconciliation before being reactivated. Hosts coordinate producer/worker tail routing at cutover and recover rejected deliveries through ordinary retry. RevenueNativeAnalyticsReader resolves the active generation for reports. GetProgressAsync exposes observed counts and latest observed event time; neither that timestamp, a UUID cursor nor a count of seen events proves source completeness.
RevenueAnalyticsRebuildService adds durable scoped capture/page intents, restartable bounded ingestion, source/fact manifest verification, seal/activation recovery and safe health reporting around these native primitives. Applications provide an independently complete immutable capture and hold a trusted routing/tail barrier through cutover; the service does not infer completeness from live history. The configured event reader preserves source provenance across optional raw expiry, and upcast changes require a fresh generation. See resumable rebuild contracts, example and limits.
Register RevenueAnalyticsService as an event consumer (or enroll retained history with the existing event backfill service). Monthly recurring revenue includes observed active, renewing paid subscriptions; yearly prices divide by 12 and daily/weekly prices use 30.4375 days per month. Reports expose observed realized customer lifetime net revenue, original-store/account attribution, product revenue, cohorts, trials, renewal stops and churn. They do not predict future lifetime value. Monetary subscription snapshots must retain their original event revision; missing historical snapshots fail delivery instead of using newer terms.
Complimentary consideration preserves the original catalog price and provider attribution while recording zero paid money and zero MRR. Immutable financial/subscription facts and transaction exports retain Consideration; native writers reject complimentary facts with nonzero money or MRR. Gift orders and active subscriptions remain visible in operational counts, while paying-customer, paid-purchase, trial-conversion and paid LTV cohorts require positive payment evidence. A zero-payment discount retains Payment consideration and its ordinary subscription pricing semantics. These rules use consideration rather than a provider name.
Refund projections use EffectiveAppliedAmountMinor. Native evidence already covered by a canonical full refund retains its reported amount with zero additional applied money and emits a nonfinancial coverage event. Canonical reversal compensates the actual retained monetary effects; evidence aliases never inflate refunds or reversal revenue.
Run StartDueAsync from an application scheduler and AdvanceAsync until completed, using distinct stable command IDs per action. Each later due run starts from the schedule's fixed initial coverage start, with fresh cursors, and re-exports that cumulative range. This recovers late commits and inserts behind earlier live cursors. Rows counts exported rows, including repeats from earlier runs. Sinks deduplicate scoped batch IDs; downstream analytics must additionally deduplicate source kind and source row ID across runs. Resource exports include both original purchased credits and subsequent lifecycle entries. Reconfiguring a schedule resets its coverage start to next-due minus interval; the host must catch up an older range before intentionally moving that boundary. The simple cumulative strategy trades growing scan volume for recovery without pretending to have a database ingestion watermark.
Financial export selection uses projection recorded time; accounting event time remains a separate column. Resource exports select immutable ledger event time. CSV escapes quotes and neutralizes formula-leading text. Batches contain allowlisted fields, without raw provider payloads or user metadata. Dispatch RevenueExportConsumer through the durable event dispatcher; remote sink calls happen after commit. RevenueFileExportSink atomically creates an extension-independent .export file in an application-owned private directory and rejects a different payload at the same scoped batch identity, including format changes. The configured batch format determines how to read those bytes.
Configure RevenueScheduledExports with analyticsStore and analyticsGeneration to use filtered native financial/resource pages. Each run pins its generation; recovery rejects a mismatched store generation. Export checkpoint, batch payload, receipt and outbound event still share the operational store transaction. The native reader does not load unrelated commerce documents. Cumulative coverage still re-emits earlier source IDs intentionally so late facts behind an old cursor recover; downstream source deduplication remains required.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- RevenueFlow.Commerce.Abstractions (>= 0.1.0-alpha.7.2)
- RevenueFlow.Events (>= 0.1.0-alpha.7.2)
- RevenueFlow.Growth.Abstractions (>= 0.1.0-alpha.7.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0-alpha.7.2 | 52 | 11/10/2026 |