Metadata-Version: 2.4
Name: founderstat
Version: 1.0.0rc1
Summary: FounderStat SDK — non-blocking, at-least-once ingestion of normalized payment events.
Author: FounderStat
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://founderstat.uz
Project-URL: Repository, https://github.com/Shavkat07/FounderStatSDK
Project-URL: Documentation, https://github.com/Shavkat07/FounderStatSDK/blob/main/docs/quickstart.md
Keywords: founderstat,analytics,mrr,saas-metrics,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pydantic>=2.5; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# founderstat (Python SDK)

Non-blocking, at-least-once ingestion of normalized payment events into
FounderStat. The reference implementation and the executable form of the event
contract.

> **Status:** `1.0.0rc1`. Phases 1–4 done; Phase 5 landed — the contract-drift
> conformance test (§5.2), the language-independent `conformance/cases.yaml`, the
> quickstart / serverless / troubleshooting docs, the Click/Payme mapping recipes
> (`docs/mapping-*.md`), and runnable, CI-tested `examples/`
> (fastapi_click, django_payme, lambda_iap, backfill_from_postgres). Contract, config,
> payment-system-neutral time helpers, non-blocking background delivery (dispatcher
> thread, full-jitter backoff, circuit breaker, fork-safety, `flush_on_capture`, async
> facade), a durable SQLite/WAL buffer (default, with memory fallback), local dedup, the
> amount-units sanity warning, historical `backfill`, and the operator CLI. Per v1.1 the
> SDK core carries no Click/Payme code — that knowledge lives only in the recipes and
> examples. See `../docs/SDK_Architecture_FounderStat.md` §12.

```python
import founderstat
from founderstat import FounderStat, ItemType, BillingPeriod

fs = FounderStat(api_key=os.environ["FOUNDERSTAT_INGESTION_KEY"])

fs.payment(
    payment_system="my_gateway",
    external_transaction_id=payload["transaction_id"],
    customer_external_id=user_id,
    amount="149000.00",                        # Decimal | int | str — never float
    currency="UZS",
    # occurred_at is the payment-system time, never now(). The helpers are neutral:
    # from_unix_ms / from_unix_seconds / from_naive(dt, tz). See docs/mapping-*.md.
    occurred_at=founderstat.time.from_unix_ms(payload["paid_at_ms"]),
    item_type=ItemType.SUBSCRIPTION,
    billing_period=BillingPeriod.MONTHLY,
)
```

## CLI

```bash
python -m founderstat doctor    # check config, key type, buffer, timezone + send a test event
python -m founderstat inspect --buffer-path /path/queue.db   # view queue + dead-letters
python -m founderstat replay  --buffer-path /path/queue.db   # re-queue dead-letters
python -m founderstat drain    --buffer-path /path/queue.db  # force-flush now
```

## Docs

- [Quickstart](https://github.com/Shavkat07/FounderStatSDK/blob/main/docs/quickstart.md) — integrate in ≤15 minutes.
- [Serverless](https://github.com/Shavkat07/FounderStatSDK/blob/main/docs/serverless.md) — Lambda / Cloud Functions (`flush_on_capture`).
- [Troubleshooting](https://github.com/Shavkat07/FounderStatSDK/blob/main/docs/troubleshooting.md) — `doctor`/`inspect`/`replay`/`drain`, `stats()`.
- Mapping recipes: [Click](https://github.com/Shavkat07/FounderStatSDK/blob/main/docs/mapping-click.md) · [Payme](https://github.com/Shavkat07/FounderStatSDK/blob/main/docs/mapping-payme.md).
- Runnable examples: [`python/examples/`](https://github.com/Shavkat07/FounderStatSDK/tree/main/python/examples) — `fastapi_click`, `django_payme`,
  `lambda_iap`, `backfill_from_postgres` (exercised in CI against `examples/payloads/`).

## Develop

```bash
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q
```
