{"id":35382930,"url":"https://github.com/smallbiznis/valora","last_synced_at":"2026-01-13T19:32:17.807Z","repository":{"id":330142314,"uuid":"1121729140","full_name":"smallbiznis/valora","owner":"smallbiznis","description":"Valora is an open-source billing engine focused on correctness, determinism, and operational reliability — from usage ingestion to invoicing.","archived":false,"fork":false,"pushed_at":"2026-01-06T23:19:01.000Z","size":5099,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-07T19:29:16.211Z","etag":null,"topics":["billing","billing-engine","billing-infrastructure","invoicing","observability","open-source","saas","subscription","usage-based-billing"],"latest_commit_sha":null,"homepage":"https://smallbiznis.github.io/valora-landing/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smallbiznis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T13:06:37.000Z","updated_at":"2026-01-06T14:56:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smallbiznis/valora","commit_stats":null,"previous_names":["smallbiznis/valora"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/smallbiznis/valora","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallbiznis%2Fvalora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallbiznis%2Fvalora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallbiznis%2Fvalora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallbiznis%2Fvalora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smallbiznis","download_url":"https://codeload.github.com/smallbiznis/valora/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallbiznis%2Fvalora/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28397826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["billing","billing-engine","billing-infrastructure","invoicing","observability","open-source","saas","subscription","usage-based-billing"],"created_at":"2026-01-02T05:40:35.376Z","updated_at":"2026-01-13T19:32:17.800Z","avatar_url":"https://github.com/smallbiznis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Valora OSS\n\n**Valora OSS** is an open-source **deterministic billing computation engine** for modern SaaS and platform products.\n\n![Release CI](https://github.com/smallbiznis/valora/actions/workflows/github-release.yml/badge.svg)\n![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)\n![Release](https://img.shields.io/github/v/release/smallbiznis/valora)\n![Go Version](https://img.shields.io/badge/go-1.23+-00ADD8?logo=go)\n\nValora extracts billing concerns—usage metering, pricing, subscriptions, and invoicing—out of application code and into a **dedicated, self-hosted engine** with explicit boundaries.\n\n\u003e **Valora determines what should be billed.\n\u003e It does not execute payments.**\n\n---\n\n## Why Valora Exists\n\nBilling is a **financial truth system**, not a convenience feature.\n\nIn many systems, billing logic is:\n\n- scattered across application code,\n- difficult to audit or reproduce,\n- tightly coupled with payments and entitlements,\n- fragile under scale and change.\n\nValora takes a deliberate approach:\n**make billing boring, deterministic, and explainable.**\n\nThis project is developed independently, outside of any employment responsibilities, as a space to design systems with clear boundaries, correctness, and accountability.\n\n---\n\n## What Valora Is\n\nValora is a **billing computation engine**, not an all-in-one billing platform.\n\n### Core Capabilities (v1.0 Target)\n\n- **Subscription Management**Trialing, active, past_due, and canceled states with explicit lifecycle transitions\n- **Usage Metering**Idempotent ingestion, deterministic aggregation, late and out-of-order handling\n- **Pricing Models**Flat-rate, tiered usage, and hybrid (base + usage) pricing with time-bound windows\n- **Invoicing**Deterministic line-item generation, proration, and invoice state management\n- **Multi-Tenancy**Organization-scoped isolation and authorization\n- **Audit Trail**\n  Immutable event log for all billing state changes\n\n---\n\n## Design Principles\n\nValora is built around strict principles:\n\n- **Deterministic by Design**Billing outputs are derived solely from persisted inputs and configuration.\n- **Explicit Boundaries**Billing logic is separated from payments, identity, and infrastructure concerns.\n- **Self-Hosted Ownership**Teams retain full control over billing data and logic.\n- **Composable Primitives**\n  Pricing behavior is modeled explicitly, not hidden in application code.\n\n---\n\n## Scope \u0026 Non-Goals\n\n### What Valora Is\n\nValora is a **deterministic billing computation engine** designed for modern SaaS and platform systems.\nIt extracts billing logic from application code into a dedicated, auditable system with explicit boundaries.\n\n### What Valora Is Not (v1.0)\n\nTo preserve correctness and clarity, the following are **intentionally out of scope** for v1.0:\n\n#### Payment Execution\n\n- No credit card processing, bank transfers, or settlement\n- No payment gateway integrations (Stripe, PayPal, etc.)\n- Determines *what* to bill, not *how* to collect payment\n- *Post-v1.0*: payment adapter interface\n\n#### Merchant of Record \u0026 Compliance\n\n- No tax calculation (VAT, GST, sales tax)\n- No PCI-DSS, PSD2, or regulatory automation\n- Tax amounts may be stored as external line items\n- *Post-v1.0*: tax metadata structure\n\n#### Dunning \u0026 Collections\n\n- No retry logic for failed payments\n- No automated email or recovery workflows\n- Past-due state exists, recovery is external\n- *Post-v1.0*: webhook events\n\n#### Revenue Recognition \u0026 Accounting\n\n- No GAAP / IFRS compliance\n- No deferred revenue tracking\n- Cash-basis invoice generation only\n- *Post-v1.0*: ledger API integrations\n\n#### Multi-Currency \u0026 FX\n\n- Single currency per tenant\n- No real-time FX handling\n- *Post-v1.0*: multi-currency via external FX providers\n\n#### Entitlements \u0026 Feature Gating\n\n- No access control or feature flags\n- Application layer is responsible\n- *Post-v1.0*: entitlement sync via webhooks\n\n#### Customer Self-Service UI\n\n- No built-in customer portal\n- API-first design\n- *Post-v1.0*: optional reference UI\n\n#### Advanced Analytics \u0026 Reporting\n\n- No MRR/ARR dashboards or cohort analysis\n- Raw data available via API\n- *Post-v1.0*: Valora Cloud analytics layer\n\n#### Complex Proration Models\n\n- Day-based proration only\n- Boundary rule: `[start inclusive, end exclusive]`\n- *Post-v1.0*: configurable proration strategies\n\n---\n\n## Why These Boundaries Matter\n\nBilling errors cost money, trust, and legal risk.\n\nBy limiting scope, Valora ensures:\n\n- reproducible and auditable billing outputs,\n- clear ownership of responsibilities,\n- clean integration with best-of-breed tools,\n- no black-box financial behavior.\n\nSelf-hosting is a **feature**, not a limitation:\n\n- full data ownership,\n- internal auditability,\n- no vendor lock-in,\n- compliance with data residency requirements.\n\n---\n\n## Architecture \u0026 Security\n\nFirst-class documentation is provided:\n\n- `ARCHITECTURE.md` — deterministic billing flows and trust boundaries\n- `SECURITY.md` — security scope and assumptions\n- `THREAT_MODEL.md` — lightweight threat model\n\n---\n\n## Deployment Model\n\nValora OSS is **self-hosted software**.\n\nThe adopting organization is responsible for:\n\n- infrastructure and networking,\n- TLS termination,\n- secrets management,\n- database operations and backups.\n\nValora makes minimal assumptions about the runtime environment.\n\n---\n\n## Who Valora Is For\n\nValora is designed for teams that:\n\n- are scaling beyond hardcoded billing logic,\n- operate usage-based or hybrid pricing models,\n- build long-lived SaaS or platform systems,\n- value correctness, clarity, and auditability.\n\nValora is **not a good fit** if you need:\n\n- an all-in-one billing + payments + tax solution,\n- no-code billing configuration,\n- a managed service with instant SLA guarantees.\n\n---\n\n## Roadmap (High-Level)\n\n**Toward v1.0**\n\n- Harden subscription and billing lifecycles\n- Deterministic usage ingestion\n- Invoice reproducibility guarantees\n- End-to-end billing truth tests\n- Stable APIs and semantic contracts\n\n**Post-v1.0**\n\n- Payment adapter interfaces\n- Webhook event system\n- Multi-currency support\n- Tax metadata integration\n- Optional **Valora Cloud**\n\n---\n\n## Observability\n\nGrafana dashboards expect the following metrics:\n\n- `valora_scheduler_job_runs_total`\n- `valora_scheduler_job_duration_seconds`\n- `valora_scheduler_job_timeouts_total`\n- `valora_scheduler_job_errors_total`\n- `valora_scheduler_batch_processed_total`\n- `valora_scheduler_batch_deferred_total`\n- `valora_scheduler_runloop_lag_seconds`\n\n---\n\n## License\n\nValora OSS is released under the Apache 2.0 License.\nSee the `LICENSE` file for details.\n\n---\n\n## Documentation\n\n📚 Documentation source: `./docs/docs/index.md`\n\n\u003e **Valora aims to make billing boring, predictable, and explainable**\n\u003e so teams can focus on building their products.\n\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallbiznis%2Fvalora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmallbiznis%2Fvalora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallbiznis%2Fvalora/lists"}