meterflow 0.1.0__tar.gz → 0.1.2__tar.gz

{meterflow-0.1.0 → meterflow-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.1.0
+Version: 0.1.2
 Summary: Official Python SDK for MeterFlow — usage-based billing, credit management, and metering.
 Project-URL: Homepage, https://meter-flow.com
 Project-URL: Documentation, https://meter-flow.com/guide
@@ -279,6 +279,42 @@ for start in range(0, len(events), MAX_BATCH_EVENTS):
     client.usage.record_batch(chunk, idempotency_key=f"job-42:chunk-{start // MAX_BATCH_EVENTS}")
 ```
 
+### Record quantities, not calls
+
+**A batch of 100 events is still 100 events.** Batching saves HTTP requests, not quota: each item in a `record_batch` is its own record, and your plan's monthly allowance counts records. The thing that actually moves the number is sending **one event that carries the quantity**.
+
+If your meter's aggregation is `sum`, MeterFlow adds up the `value` of its events — so one event with `value=100` is **one** event against your monthly allowance and **100 units** against the meter. Record per unit of work instead of per API call:
+
+```python
+# ❌ One event per call — 100 calls is 100 events against your plan.
+for chunk in completion.chunks:
+    client.usage.record(
+        {
+            "event_name": "tokens.used",
+            "customer_external_id": "customer_123",
+            "value": 1,
+            "properties": {},
+        }
+    )
+
+# ✅ One event carrying the quantity — 1 event against your plan, 1,300 units on the meter.
+client.usage.record(
+    {
+        "event_name": "tokens.used",
+        "customer_external_id": "customer_123",
+        "value": 1300,                       # a `sum` meter adds these up
+        "properties": {"model": "gpt-4o-mini"},
+    }
+)
+```
+
+This is usually the difference between fitting a plan and outgrowing it: 1,000 users × 100 calls a day is ~3M events a month recorded per call, and ~30k recorded per session. Aggregate in your app over whatever window you can afford to lose on a crash — a request, a job, a minute — then send one event.
+
+Two things to keep in mind:
+
+- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max`, `min` and `unique_count` read `value` as a measurement, not a quantity to add.
+- **Billing is unchanged.** A metered plan limit charges per unit — the event's `value` — so 100 units cost the same whether they arrived as 100 events or one. You are not rounding anyone's bill by batching.
+
 **Summary** — a customer's usage, broken down by meter:
 
 ```python
@@ -402,6 +438,17 @@ client.credits.deduct(
 
 Every write method accepts the keyword: `credits.grant/deduct`, `usage.record/record_batch`, `subscriptions.create/update`. Use a key that identifies the *business operation* (order ID, job ID) — not a random value per attempt, which would defeat the purpose.
 
+**A key is bound to the body you first used it with.** MeterFlow stores a fingerprint of the request alongside the key, so a retry only replays when it is genuinely the same request. Reuse the key with a *different* body and the call is refused with `ConflictError` (409) instead of quietly handing back the original record:
+
+```python
+client.credits.grant({"customer_external_id": "customer_123", "amount": 100, "metadata": {}}, idempotency_key="welcome-123")
+
+# Same key, different amount -> ConflictError. Nothing is written, and the first grant stands.
+client.credits.grant({"customer_external_id": "customer_123", "amount": 250, "metadata": {}}, idempotency_key="welcome-123")
+```
+
+That is deliberate: silently returning the first record would turn two different operations into one and report success. One key per operation, reused only to retry that same operation. Keys stay namespaced per environment, so a `mf_test_` and a `mf_live_` key never collide.
+
 ## Automatic retries
 
 The SDK retries transient failures for you — exponential backoff with jitter, 3 attempts by default:
@@ -434,7 +481,7 @@ Every error carries:
 
 - **`request_id`** — the API's `X-Request-ID` for that call. Include it when contacting support; it pinpoints the exact request in our logs.
 - **`status_code`**, **`error_type`**, and **`retryable`** — for programmatic handling and structured logging.
-- **`message`** (also `str(err)`) — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 5,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`[{"field": ..., "message": ...}]`).
+- **`message`** (also `str(err)`) — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 50,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`[{"field": ..., "message": ...}]`).
 
 ```python
 from meterflow import MeterFlowError, InsufficientCreditsError, RateLimitError
@@ -491,6 +538,10 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
+| `balance.low` | a deduction takes a customer's balance **down through** this endpoint's `low_balance_threshold` — a crossing, so it fires once and not again while they stay below. Needs the threshold set on the webhook; without one it never fires | `customer_id`, `balance`, `threshold`, `transaction_id` |
+| `balance.exhausted` | a balance reaches zero, **or** a request is refused for want of credits (a deduction returning 402, or `entitlements.check` answering `insufficient_credits`). Unlike `balance.low` this repeats: every refused request is its own blocked request | `customer_id`, `balance`, `reason` (`balance_zero` / `insufficient_credits`), `requested_amount` and `feature` where they apply, `transaction_id` on the zero case |
+| `subscription.renewed` | a billing period rolls forward (the renewer; no `subscription.updated` is emitted for a renewal) | `customer_id`, `subscription_id`, `plan_id`, `current_period_start`, `current_period_end`, `credits_granted` |
+| `subscription.canceled` | a subscription's status becomes canceled — fired **alongside** `subscription.updated`, once, on the call that actually cancels | `customer_id`, `subscription_id`, `plan_id`, `canceled_at` |
 
 For example, a `credit.granted` delivery:
 

{meterflow-0.1.0 → meterflow-0.1.2}/README.md

@@ -227,6 +227,42 @@ for start in range(0, len(events), MAX_BATCH_EVENTS):
     client.usage.record_batch(chunk, idempotency_key=f"job-42:chunk-{start // MAX_BATCH_EVENTS}")
 ```
 
+### Record quantities, not calls
+
+**A batch of 100 events is still 100 events.** Batching saves HTTP requests, not quota: each item in a `record_batch` is its own record, and your plan's monthly allowance counts records. The thing that actually moves the number is sending **one event that carries the quantity**.
+
+If your meter's aggregation is `sum`, MeterFlow adds up the `value` of its events — so one event with `value=100` is **one** event against your monthly allowance and **100 units** against the meter. Record per unit of work instead of per API call:
+
+```python
+# ❌ One event per call — 100 calls is 100 events against your plan.
+for chunk in completion.chunks:
+    client.usage.record(
+        {
+            "event_name": "tokens.used",
+            "customer_external_id": "customer_123",
+            "value": 1,
+            "properties": {},
+        }
+    )
+
+# ✅ One event carrying the quantity — 1 event against your plan, 1,300 units on the meter.
+client.usage.record(
+    {
+        "event_name": "tokens.used",
+        "customer_external_id": "customer_123",
+        "value": 1300,                       # a `sum` meter adds these up
+        "properties": {"model": "gpt-4o-mini"},
+    }
+)
+```
+
+This is usually the difference between fitting a plan and outgrowing it: 1,000 users × 100 calls a day is ~3M events a month recorded per call, and ~30k recorded per session. Aggregate in your app over whatever window you can afford to lose on a crash — a request, a job, a minute — then send one event.
+
+Two things to keep in mind:
+
+- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max`, `min` and `unique_count` read `value` as a measurement, not a quantity to add.
+- **Billing is unchanged.** A metered plan limit charges per unit — the event's `value` — so 100 units cost the same whether they arrived as 100 events or one. You are not rounding anyone's bill by batching.
+
 **Summary** — a customer's usage, broken down by meter:
 
 ```python
@@ -350,6 +386,17 @@ client.credits.deduct(
 
 Every write method accepts the keyword: `credits.grant/deduct`, `usage.record/record_batch`, `subscriptions.create/update`. Use a key that identifies the *business operation* (order ID, job ID) — not a random value per attempt, which would defeat the purpose.
 
+**A key is bound to the body you first used it with.** MeterFlow stores a fingerprint of the request alongside the key, so a retry only replays when it is genuinely the same request. Reuse the key with a *different* body and the call is refused with `ConflictError` (409) instead of quietly handing back the original record:
+
+```python
+client.credits.grant({"customer_external_id": "customer_123", "amount": 100, "metadata": {}}, idempotency_key="welcome-123")
+
+# Same key, different amount -> ConflictError. Nothing is written, and the first grant stands.
+client.credits.grant({"customer_external_id": "customer_123", "amount": 250, "metadata": {}}, idempotency_key="welcome-123")
+```
+
+That is deliberate: silently returning the first record would turn two different operations into one and report success. One key per operation, reused only to retry that same operation. Keys stay namespaced per environment, so a `mf_test_` and a `mf_live_` key never collide.
+
 ## Automatic retries
 
 The SDK retries transient failures for you — exponential backoff with jitter, 3 attempts by default:
@@ -382,7 +429,7 @@ Every error carries:
 
 - **`request_id`** — the API's `X-Request-ID` for that call. Include it when contacting support; it pinpoints the exact request in our logs.
 - **`status_code`**, **`error_type`**, and **`retryable`** — for programmatic handling and structured logging.
-- **`message`** (also `str(err)`) — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 5,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`[{"field": ..., "message": ...}]`).
+- **`message`** (also `str(err)`) — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 50,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`[{"field": ..., "message": ...}]`).
 
 ```python
 from meterflow import MeterFlowError, InsufficientCreditsError, RateLimitError
@@ -439,6 +486,10 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
+| `balance.low` | a deduction takes a customer's balance **down through** this endpoint's `low_balance_threshold` — a crossing, so it fires once and not again while they stay below. Needs the threshold set on the webhook; without one it never fires | `customer_id`, `balance`, `threshold`, `transaction_id` |
+| `balance.exhausted` | a balance reaches zero, **or** a request is refused for want of credits (a deduction returning 402, or `entitlements.check` answering `insufficient_credits`). Unlike `balance.low` this repeats: every refused request is its own blocked request | `customer_id`, `balance`, `reason` (`balance_zero` / `insufficient_credits`), `requested_amount` and `feature` where they apply, `transaction_id` on the zero case |
+| `subscription.renewed` | a billing period rolls forward (the renewer; no `subscription.updated` is emitted for a renewal) | `customer_id`, `subscription_id`, `plan_id`, `current_period_start`, `current_period_end`, `credits_granted` |
+| `subscription.canceled` | a subscription's status becomes canceled — fired **alongside** `subscription.updated`, once, on the call that actually cancels | `customer_id`, `subscription_id`, `plan_id`, `canceled_at` |
 
 For example, a `credit.granted` delivery:
 

{meterflow-0.1.0 → meterflow-0.1.2}/src/meterflow/_version.py

@@ -1,3 +1,3 @@
 # The one place the version lives. pyproject.toml reads it (hatch dynamic version) and the
 # User-Agent header reports it, so a release bump edits this file and nothing else.
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{meterflow-0.1.0 → meterflow-0.1.2}/src/meterflow/resources/usage.py

@@ -29,6 +29,10 @@ def record_batch_spec(events: list[UsageEventRequest], idempotency_key: str | No
     return RequestSpec("POST", "usage/events/batch", body={"events": events}, idempotency_key=idempotency_key)
 
 
+def event_spec(event_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"usage/events/{encode_path_segment(event_id)}")
+
+
 def summary_spec(customer_id: str, meter_id: str | None, from_: str | None, to: str | None) -> RequestSpec:
     return RequestSpec("GET", f"usage/{encode_path_segment(customer_id)}", query={"meter_id": meter_id, "from_": from_, "to": to})
 
@@ -47,6 +51,16 @@ class UsageResource:
         result: list[UsageEventResponse] = self._client.request(record_batch_spec(events, idempotency_key))
         return result
 
+    def event(self, event_id: str) -> UsageEventResponse:
+        """Read one recorded event back, with ``billing_outcome`` — what the worker decided.
+
+        One of ``charged``, ``no_subscription``, ``no_meter_limit``, ``not_metered``,
+        ``within_allowance`` or ``not_deducted``, and ``None`` while ``processed`` is False: the
+        worker runs after ``record`` answers, so poll this to learn what happened to a charge.
+        """
+        result: UsageEventResponse = self._client.request(event_spec(event_id))
+        return result
+
     def summary(
         self, customer_id: str, *, meter_id: str | None = None, from_: str | None = None, to: str | None = None
     ) -> UsageSummaryResponse:
@@ -69,6 +83,16 @@ class AsyncUsageResource:
         result: list[UsageEventResponse] = await self._client.request(record_batch_spec(events, idempotency_key))
         return result
 
+    async def event(self, event_id: str) -> UsageEventResponse:
+        """Read one recorded event back, with ``billing_outcome`` — what the worker decided.
+
+        One of ``charged``, ``no_subscription``, ``no_meter_limit``, ``not_metered``,
+        ``within_allowance`` or ``not_deducted``, and ``None`` while ``processed`` is False: the
+        worker runs after ``record`` answers, so poll this to learn what happened to a charge.
+        """
+        result: UsageEventResponse = await self._client.request(event_spec(event_id))
+        return result
+
     async def summary(
         self, customer_id: str, *, meter_id: str | None = None, from_: str | None = None, to: str | None = None
     ) -> UsageSummaryResponse:

{meterflow-0.1.0 → meterflow-0.1.2}/src/meterflow/types.py

@@ -16,6 +16,7 @@ SubscriptionStatus = Literal["active", "trialing", "past_due", "paused", "cancel
 class CreditBalanceResponse(TypedDict):
     id: str
     project_id: str
+    environment: str
     customer_external_id: str
     balance: str
     total_granted: str
@@ -50,6 +51,7 @@ class CreditGrantRequest(_CreditGrantRequestRequired, total=False):
 class CreditTransactionResponse(TypedDict):
     id: str
     project_id: str
+    environment: str
     customer_external_id: str
     transaction_type: str
     amount: str
@@ -107,6 +109,7 @@ class PlanResponse(TypedDict):
     trial_days: int
     is_active: bool
     is_public: bool
+    is_published: bool
     metadata_: dict[str, Any]
     meter_limits: list[PlanMeterLimitResponse]
     features: list[str]
@@ -127,6 +130,7 @@ class SubscriptionCreateRequest(_SubscriptionCreateRequestRequired, total=False)
 class SubscriptionResponse(TypedDict):
     id: str
     project_id: str
+    environment: str
     plan_id: str
     customer_external_id: str
     status: str
@@ -160,9 +164,10 @@ class UsageEventRequest(_UsageEventRequestRequired, total=False):
     timestamp: str | None
 
 
-class UsageEventResponse(TypedDict):
+class _UsageEventResponseRequired(TypedDict):
     id: str
     project_id: str
+    environment: str
     meter_id: str
     customer_external_id: str
     event_name: str
@@ -174,7 +179,12 @@ class UsageEventResponse(TypedDict):
     created_at: str
 
 
-class UsageSummaryItem(TypedDict):
+class UsageEventResponse(_UsageEventResponseRequired, total=False):
+    billing_outcome: str | None
+    processed_at: str | None
+
+
+class _UsageSummaryItemRequired(TypedDict):
     meter_id: str
     meter_name: str
     event_name: str
@@ -183,6 +193,11 @@ class UsageSummaryItem(TypedDict):
     event_count: int
 
 
+class UsageSummaryItem(_UsageSummaryItemRequired, total=False):
+    first_event_at: str | None
+    last_event_at: str | None
+
+
 class UsageSummaryResponse(TypedDict):
     project_id: str
     customer_external_id: str