@pithy-sh/payments 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (177) hide show
  1. package/README.md +10 -3
  2. package/dist/admin/coverage.d.ts.map +1 -1
  3. package/dist/admin/coverage.js +26 -2
  4. package/dist/admin/read.d.ts +48 -1
  5. package/dist/admin/read.d.ts.map +1 -1
  6. package/dist/admin/read.js +89 -2
  7. package/dist/audit/actions.d.ts +13 -0
  8. package/dist/audit/actions.d.ts.map +1 -1
  9. package/dist/audit/actions.js +14 -1
  10. package/dist/capability.d.ts +33 -2
  11. package/dist/capability.d.ts.map +1 -1
  12. package/dist/capability.js +52 -9
  13. package/dist/client/api.d.ts +19 -0
  14. package/dist/client/api.d.ts.map +1 -1
  15. package/dist/client/api.js +34 -1
  16. package/dist/client/hooks.d.ts +20 -1
  17. package/dist/client/hooks.d.ts.map +1 -1
  18. package/dist/client/hooks.js +40 -2
  19. package/dist/client/projection.d.ts +29 -0
  20. package/dist/client/projection.d.ts.map +1 -1
  21. package/dist/config/allowances.d.ts +71 -0
  22. package/dist/config/allowances.d.ts.map +1 -0
  23. package/dist/config/allowances.js +115 -0
  24. package/dist/config/config.d.ts +155 -9
  25. package/dist/config/config.d.ts.map +1 -1
  26. package/dist/config/config.js +164 -14
  27. package/dist/data/meterCounter.d.ts +34 -0
  28. package/dist/data/meterCounter.d.ts.map +1 -0
  29. package/dist/data/meterCounter.js +33 -0
  30. package/dist/data/override.d.ts +56 -0
  31. package/dist/data/override.d.ts.map +1 -0
  32. package/dist/data/override.js +58 -0
  33. package/dist/data/period.d.ts +10 -0
  34. package/dist/data/period.d.ts.map +1 -0
  35. package/dist/data/period.js +37 -0
  36. package/dist/data/purchase.d.ts +1 -0
  37. package/dist/data/purchase.d.ts.map +1 -1
  38. package/dist/data/purchase.js +1 -0
  39. package/dist/data/tables.d.ts +17 -1
  40. package/dist/data/tables.d.ts.map +1 -1
  41. package/dist/data/tables.js +24 -4
  42. package/dist/data/usageReport.d.ts +68 -0
  43. package/dist/data/usageReport.d.ts.map +1 -0
  44. package/dist/data/usageReport.js +55 -0
  45. package/dist/data/usageRun.d.ts +93 -0
  46. package/dist/data/usageRun.d.ts.map +1 -0
  47. package/dist/data/usageRun.js +50 -0
  48. package/dist/entitlement/allowance.d.ts +100 -0
  49. package/dist/entitlement/allowance.d.ts.map +1 -0
  50. package/dist/entitlement/allowance.js +171 -0
  51. package/dist/entitlement/manual.d.ts +5 -5
  52. package/dist/entitlement/manual.js +3 -3
  53. package/dist/entitlement/meter.d.ts +98 -0
  54. package/dist/entitlement/meter.d.ts.map +1 -0
  55. package/dist/entitlement/meter.js +177 -0
  56. package/dist/entitlement/override.d.ts +119 -0
  57. package/dist/entitlement/override.d.ts.map +1 -0
  58. package/dist/entitlement/override.js +256 -0
  59. package/dist/entitlement/resolver.d.ts +2 -1
  60. package/dist/entitlement/resolver.d.ts.map +1 -1
  61. package/dist/entitlement/resolver.js +32 -1
  62. package/dist/error/errors.d.ts +19 -0
  63. package/dist/error/errors.d.ts.map +1 -1
  64. package/dist/error/errors.js +35 -2
  65. package/dist/http/responses.d.ts +367 -0
  66. package/dist/http/responses.d.ts.map +1 -1
  67. package/dist/http/responses.js +146 -7
  68. package/dist/http/routes.d.ts.map +1 -1
  69. package/dist/http/routes.js +270 -16
  70. package/dist/http/schemas.d.ts +54 -0
  71. package/dist/http/schemas.d.ts.map +1 -1
  72. package/dist/http/schemas.js +61 -2
  73. package/dist/http/scopes.d.ts +25 -0
  74. package/dist/http/scopes.d.ts.map +1 -1
  75. package/dist/http/scopes.js +60 -1
  76. package/dist/http/view.d.ts +22 -4
  77. package/dist/http/view.d.ts.map +1 -1
  78. package/dist/http/view.js +88 -7
  79. package/dist/index.d.ts +2 -1
  80. package/dist/index.d.ts.map +1 -1
  81. package/dist/index.js +3 -2
  82. package/dist/migrations/0002_allowances.d.ts +26 -0
  83. package/dist/migrations/0002_allowances.d.ts.map +1 -0
  84. package/dist/migrations/0002_allowances.js +62 -0
  85. package/dist/peer.d.ts +1 -0
  86. package/dist/peer.d.ts.map +1 -1
  87. package/dist/projection/event.d.ts +1 -0
  88. package/dist/projection/event.d.ts.map +1 -1
  89. package/dist/projection/event.js +1 -0
  90. package/dist/projection/writer.d.ts.map +1 -1
  91. package/dist/projection/writer.js +3 -1
  92. package/dist/rails/contract.d.ts +6 -0
  93. package/dist/rails/contract.d.ts.map +1 -1
  94. package/dist/rails/google/playApi.d.ts.map +1 -1
  95. package/dist/rails/google/playApi.js +2 -0
  96. package/dist/rails/paddle/objects.d.ts +2 -0
  97. package/dist/rails/paddle/objects.d.ts.map +1 -1
  98. package/dist/rails/paddle/objects.js +7 -2
  99. package/dist/rails/paddle/usage.d.ts +11 -0
  100. package/dist/rails/paddle/usage.d.ts.map +1 -0
  101. package/dist/rails/paddle/usage.js +49 -0
  102. package/dist/rails/quantity.d.ts +12 -0
  103. package/dist/rails/quantity.d.ts.map +1 -0
  104. package/dist/rails/quantity.js +16 -0
  105. package/dist/rails/stripe/checkout.d.ts.map +1 -1
  106. package/dist/rails/stripe/checkout.js +1 -1
  107. package/dist/rails/stripe/objects.d.ts.map +1 -1
  108. package/dist/rails/stripe/objects.js +3 -0
  109. package/dist/rails/stripe/usage.d.ts +10 -0
  110. package/dist/rails/stripe/usage.d.ts.map +1 -0
  111. package/dist/rails/stripe/usage.js +49 -0
  112. package/dist/usage/pass.d.ts +120 -0
  113. package/dist/usage/pass.d.ts.map +1 -0
  114. package/dist/usage/pass.js +363 -0
  115. package/dist/usage/reporter.d.ts +36 -0
  116. package/dist/usage/reporter.d.ts.map +1 -0
  117. package/dist/usage/reporter.js +2 -0
  118. package/dist/version.generated.d.ts +1 -1
  119. package/dist/version.generated.js +1 -1
  120. package/dist/workflows/specs.d.ts +28 -0
  121. package/dist/workflows/specs.d.ts.map +1 -1
  122. package/dist/workflows/specs.js +26 -1
  123. package/dist/workflows/usage.d.ts +38 -0
  124. package/dist/workflows/usage.d.ts.map +1 -0
  125. package/dist/workflows/usage.js +77 -0
  126. package/dist/workflows/worker.js +2 -2
  127. package/docs/entitlements.md +249 -0
  128. package/docs/lemon-squeezy.md +1 -0
  129. package/docs/paddle.md +1 -0
  130. package/package.json +5 -5
  131. package/pithy.manifest.json +3 -8
  132. package/src/admin/coverage.ts +28 -0
  133. package/src/admin/read.ts +173 -1
  134. package/src/audit/actions.ts +13 -0
  135. package/src/capability.ts +87 -9
  136. package/src/client/api.ts +44 -0
  137. package/src/client/hooks.ts +44 -0
  138. package/src/client/projection.ts +31 -0
  139. package/src/config/allowances.ts +211 -0
  140. package/src/config/config.ts +283 -15
  141. package/src/data/meterCounter.ts +38 -0
  142. package/src/data/override.ts +74 -0
  143. package/src/data/period.ts +53 -0
  144. package/src/data/purchase.ts +9 -0
  145. package/src/data/tables.ts +25 -1
  146. package/src/data/usageReport.ts +64 -0
  147. package/src/data/usageRun.ts +66 -0
  148. package/src/entitlement/allowance.ts +213 -0
  149. package/src/entitlement/manual.ts +6 -6
  150. package/src/entitlement/meter.ts +252 -0
  151. package/src/entitlement/override.ts +381 -0
  152. package/src/entitlement/resolver.ts +43 -2
  153. package/src/error/errors.ts +44 -1
  154. package/src/http/responses.ts +305 -4
  155. package/src/http/routes.ts +365 -11
  156. package/src/http/schemas.ts +139 -1
  157. package/src/http/scopes.ts +68 -0
  158. package/src/http/view.ts +112 -7
  159. package/src/index.ts +18 -0
  160. package/src/migrations/0002_allowances.ts +149 -0
  161. package/src/projection/event.ts +9 -0
  162. package/src/projection/writer.ts +4 -0
  163. package/src/rails/contract.ts +6 -0
  164. package/src/rails/google/playApi.ts +2 -0
  165. package/src/rails/paddle/fixtures/subscription-charge.json +19 -0
  166. package/src/rails/paddle/objects.ts +6 -0
  167. package/src/rails/paddle/usage.ts +66 -0
  168. package/src/rails/quantity.ts +14 -0
  169. package/src/rails/stripe/checkout.ts +3 -1
  170. package/src/rails/stripe/fixtures/meter-event-created.json +12 -0
  171. package/src/rails/stripe/objects.ts +4 -0
  172. package/src/rails/stripe/usage.ts +61 -0
  173. package/src/usage/pass.ts +539 -0
  174. package/src/usage/reporter.ts +38 -0
  175. package/src/version.generated.ts +1 -1
  176. package/src/workflows/specs.ts +34 -0
  177. package/src/workflows/usage.ts +97 -0
@@ -6,6 +6,7 @@ import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
6
6
  import { safeEmit } from "@pithy-sh/core/src/controlPlane/audit/actions";
7
7
  import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
8
8
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
9
+ import { grantedEntitlementKeys } from "@pithy-sh/core/src/entitlement/entitlement";
9
10
  import { InternalError, NotFoundError, PithyError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
10
11
  import { memoryJwksCache } from "@pithy-sh/core/src/http/oidcWebhook";
11
12
  import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
@@ -14,7 +15,17 @@ import { resolveWorkflowBinding } from "@pithy-sh/core/src/workflow/dispatch";
14
15
  import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
15
16
  import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
16
17
  import type { Context, Hono } from "hono";
17
- import { listEntitlements, listPurchases, listReconcileRuns, listSubscriptions, readEntitlements } from "../admin/read";
18
+ import {
19
+ lastReports,
20
+ listEntitlements,
21
+ listOverrides,
22
+ listPurchases,
23
+ listReconcileRuns,
24
+ listSubscriptions,
25
+ listUsageRuns,
26
+ readEntitlements,
27
+ unrestrictedSubjects,
28
+ } from "../admin/read";
18
29
  import { type PaymentsAuditAction, PaymentsAuditActions } from "../audit/actions";
19
30
  import {
20
31
  type PaymentsCatalogEntry,
@@ -44,7 +55,19 @@ import {
44
55
  } from "../data/subscription";
45
56
  import { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } from "../data/tables";
46
57
  import { WEBHOOK_EVENT_ORPHANED } from "../data/webhookEvent";
58
+ import { resolveAllowances } from "../entitlement/allowance";
47
59
  import { grantEntitlement, revokeEntitlement } from "../entitlement/manual";
60
+ import { allowanceInputFor } from "../entitlement/meter";
61
+ import {
62
+ allowanceOverride,
63
+ clearOverride,
64
+ type OverrideChange,
65
+ overrideCeiling,
66
+ overrideVersion,
67
+ readOverride,
68
+ setOverride,
69
+ setUnrestricted,
70
+ } from "../entitlement/override";
48
71
  import { type PaymentsSubjectSeam, requirePaymentsSubject, resolvePaymentsSubject } from "../entitlement/subjectSeam";
49
72
  import {
50
73
  PaymentsEntitlementNotInCatalogError,
@@ -80,15 +103,18 @@ import {
80
103
  PaymentsAdminCatalogResponse,
81
104
  PaymentsAdminDiscountsResponse,
82
105
  PaymentsAdminEntitlementsResponse,
106
+ PaymentsAdminOverridesResponse,
83
107
  PaymentsAdminPurchasesResponse,
84
108
  PaymentsAdminReconcileRunStarted,
85
109
  PaymentsAdminReconcileRunsResponse,
86
110
  PaymentsAdminSubjectEntitlementsResponse,
87
111
  PaymentsAdminSubscriptionsResponse,
112
+ PaymentsAdminUsageRunsResponse,
88
113
  PaymentsCheckoutHandoffResponse,
89
114
  PaymentsDiscountResponse,
90
115
  PaymentsEntitlementResponse,
91
116
  PaymentsEntitlementsResponse,
117
+ PaymentsOverrideResponse,
92
118
  PaymentsPortalHandoffResponse,
93
119
  PaymentsPricingEnvelope,
94
120
  type PaymentsPricingResponse,
@@ -107,10 +133,12 @@ import {
107
133
  import {
108
134
  AdminDiscountsQuery,
109
135
  AdminEntitlementsQuery,
136
+ AdminOverridesQuery,
110
137
  AdminPurchasesQuery,
111
138
  AdminReconcileRunsQuery,
112
139
  AdminSubjectParam,
113
140
  AdminSubscriptionsQuery,
141
+ AdminUsageRunsQuery,
114
142
  AppleWebhookNotification,
115
143
  CheckoutRequest,
116
144
  DiscountCreateRequest,
@@ -118,6 +146,9 @@ import {
118
146
  EntitlementRevokeRequest,
119
147
  GoogleWebhookNotification,
120
148
  LemonSqueezyWebhookNotification,
149
+ OverrideClearRequest,
150
+ OverrideSetRequest,
151
+ OverrideUnrestrictedRequest,
121
152
  PaddleResumeQuery,
122
153
  PaddleWebhookNotification,
123
154
  PurchaseSubmission,
@@ -134,17 +165,25 @@ import {
134
165
  PAYMENTS_ENTITLEMENT_GRANT_SCOPE,
135
166
  PAYMENTS_ENTITLEMENT_REVOKE_SCOPE,
136
167
  PAYMENTS_ENTITLEMENTS_READ_SCOPE,
168
+ PAYMENTS_OVERRIDE_CLEAR_SCOPE,
169
+ PAYMENTS_OVERRIDE_SET_SCOPE,
170
+ PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE,
137
171
  PAYMENTS_PURCHASES_READ_SCOPE,
138
172
  PAYMENTS_RECONCILE_READ_SCOPE,
139
173
  PAYMENTS_RECONCILE_RUN_SCOPE,
140
174
  PAYMENTS_SUBSCRIPTIONS_READ_SCOPE,
175
+ PAYMENTS_USAGE_READ_SCOPE,
141
176
  } from "./scopes";
142
177
  import {
178
+ adminAllowancesView,
143
179
  adminCatalogView,
144
180
  adminEntitlementView,
181
+ adminOverrideView,
145
182
  adminPurchaseView,
146
183
  adminReconcileRunView,
184
+ adminUsageRunView,
147
185
  entitlementView,
186
+ overrideView,
148
187
  purchaseView,
149
188
  } from "./view";
150
189
  import { completeWebhook, requireSignedWebhook, verifiedWebhook } from "./webhookGuard";
@@ -1395,7 +1434,7 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1395
1434
  );
1396
1435
  return c.json(
1397
1436
  {
1398
- purchases: page.items.map(adminPurchaseView),
1437
+ purchases: page.items.map((row) => adminPurchaseView(row)),
1399
1438
  nextCursor: page.nextCursor,
1400
1439
  } satisfies PaymentsAdminPurchasesResponse,
1401
1440
  200,
@@ -1426,6 +1465,14 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1426
1465
  const query = c.req.valid("query");
1427
1466
  const subject = subjectFilter(query);
1428
1467
  const page = await listSubscriptions(database(c), { ...query, subject });
1468
+ const reported = await lastReports(
1469
+ database(c),
1470
+ page.items.flatMap((row) =>
1471
+ row.originalTransactionId === null
1472
+ ? []
1473
+ : [{ rail: row.rail, providerSubscriptionId: row.originalTransactionId }],
1474
+ ),
1475
+ );
1429
1476
  await recordRead(
1430
1477
  c,
1431
1478
  PaymentsAuditActions.subscriptionsRead,
@@ -1442,7 +1489,9 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1442
1489
  );
1443
1490
  return c.json(
1444
1491
  {
1445
- subscriptions: page.items.map(adminPurchaseView),
1492
+ subscriptions: page.items.map((row) =>
1493
+ adminPurchaseView(row, reported.get(`${row.rail}:${row.originalTransactionId}`) ?? null),
1494
+ ),
1446
1495
  nextCursor: page.nextCursor,
1447
1496
  } satisfies PaymentsAdminSubscriptionsResponse,
1448
1497
  200,
@@ -1472,6 +1521,9 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1472
1521
  const now = clock();
1473
1522
  const subject = subjectFilter(query);
1474
1523
  const page = await listEntitlements(database(c), { ...query, subject });
1524
+ // Which of the page's subjects are unrestricted, in one read — marked on every row, because the
1525
+ // largest grant the kit has must be visible wherever its holder is.
1526
+ const unrestricted = await unrestrictedSubjects(database(c), page.items);
1475
1527
  await recordRead(
1476
1528
  c,
1477
1529
  PaymentsAuditActions.entitlementsRead,
@@ -1488,7 +1540,9 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1488
1540
  );
1489
1541
  return c.json(
1490
1542
  {
1491
- entitlements: page.items.map((row) => adminEntitlementView(row, now)),
1543
+ entitlements: page.items.map((row) =>
1544
+ adminEntitlementView(row, now, unrestricted.has(encodeSubjectReference(row))),
1545
+ ),
1492
1546
  nextCursor: page.nextCursor,
1493
1547
  } satisfies PaymentsAdminEntitlementsResponse,
1494
1548
  200,
@@ -1496,6 +1550,62 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1496
1550
  },
1497
1551
  );
1498
1552
 
1553
+ /**
1554
+ * CONTROL PLANE. Every subject's override, most recently changed first.
1555
+ *
1556
+ * The read the override writes are paired with, on the entitlement read's scope: what a subject may have
1557
+ * is one question with its entitlements, and an operator who can see one can see the other. Filterable to
1558
+ * `unrestricted=true`, because "who holds the whole product" must be a question anyone holding this scope
1559
+ * can answer in one request.
1560
+ */
1561
+ app.get(
1562
+ `${base}/admin/overrides`,
1563
+ describeRoute({
1564
+ summary: "Read every subject's override, page by page.",
1565
+ verification: "control-plane",
1566
+ scopes: [PAYMENTS_ENTITLEMENTS_READ_SCOPE],
1567
+ responses: { 200: PaymentsAdminOverridesResponse },
1568
+ }),
1569
+ requireControlPlane(PAYMENTS_ENTITLEMENTS_READ_SCOPE),
1570
+ validate("query", AdminOverridesQuery),
1571
+ async (c) => {
1572
+ const query = c.req.valid("query");
1573
+ const subject = subjectFilter(query);
1574
+ const unrestricted = query.unrestricted === undefined ? undefined : query.unrestricted === "true";
1575
+ const page = await listOverrides(database(c), {
1576
+ ...(subject ? { subject } : {}),
1577
+ ...(unrestricted === undefined ? {} : { unrestricted }),
1578
+ ...(query.cursor ? { cursor: query.cursor } : {}),
1579
+ ...(query.limit ? { limit: query.limit } : {}),
1580
+ });
1581
+ await recordRead(
1582
+ c,
1583
+ PaymentsAuditActions.entitlementsRead,
1584
+ subject === undefined ? null : encodeSubjectReference(subject),
1585
+ {
1586
+ returned: page.items.length,
1587
+ resumed: query.cursor !== undefined,
1588
+ filters: {
1589
+ subjectType: subject?.subjectType ?? null,
1590
+ subjectId: subject?.subjectId ?? null,
1591
+ unrestricted: unrestricted ?? null,
1592
+ },
1593
+ },
1594
+ );
1595
+ return c.json(
1596
+ {
1597
+ overrides: page.items.map((row) => ({
1598
+ subjectType: row.subjectType,
1599
+ subjectId: row.subjectId,
1600
+ override: overrideView(row),
1601
+ })),
1602
+ nextCursor: page.nextCursor,
1603
+ } satisfies PaymentsAdminOverridesResponse,
1604
+ 200,
1605
+ );
1606
+ },
1607
+ );
1608
+
1499
1609
  /**
1500
1610
  * CONTROL PLANE. Everything one subject is entitled to, resolved now.
1501
1611
  *
@@ -1524,16 +1634,30 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1524
1634
  async (c) => {
1525
1635
  const subject = c.req.valid("param");
1526
1636
  const now = clock();
1527
- const rows = await readEntitlements(database(c), subject);
1637
+ const d1 = database(c);
1638
+ const rows = await readEntitlements(d1, subject);
1639
+ const override = await readOverride(paymentsDatabase(d1), subject);
1640
+ // The held keys from the rows already read, resolved against `now` exactly as the gate resolves them.
1641
+ const held = grantedEntitlementKeys(
1642
+ rows.map((row) => ({ key: row.entitlement, active: row.active, expiresAt: row.expiresAt, source: null })),
1643
+ now,
1644
+ );
1645
+ const resolved = resolveAllowances({ declarations: config, held, override: allowanceOverride(override) });
1646
+ const unrestricted = override?.unrestricted === true;
1528
1647
  await recordRead(c, PaymentsAuditActions.entitlementsRead, encodeSubjectReference(subject), {
1529
1648
  subjectType: subject.subjectType,
1530
1649
  subjectId: subject.subjectId,
1531
1650
  returned: rows.length,
1651
+ unrestricted,
1532
1652
  });
1533
1653
  return c.json(
1534
1654
  {
1535
1655
  ...subject,
1536
- entitlements: rows.map((row) => adminEntitlementView(row, now)),
1656
+ entitlements: rows.map((row) => adminEntitlementView(row, now, unrestricted)),
1657
+ unrestricted,
1658
+ overrideVersion: overrideVersion(override),
1659
+ override: adminOverrideView(override),
1660
+ allowances: adminAllowancesView(resolved, (name) => overrideCeiling(config, held, name)),
1537
1661
  } satisfies PaymentsAdminSubjectEntitlementsResponse,
1538
1662
  200,
1539
1663
  );
@@ -1578,6 +1702,40 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1578
1702
  },
1579
1703
  );
1580
1704
 
1705
+ /**
1706
+ * CONTROL PLANE. What usage reporting has done — the passes this Worker has run, newest first.
1707
+ *
1708
+ * Its own scope, separate from the reconciliation log's: a run's findings name the subjects it did not
1709
+ * report and why, which is what an operator answering "why was this customer not billed" needs and what a
1710
+ * health monitor does not.
1711
+ */
1712
+ app.get(
1713
+ `${base}/admin/usage-runs`,
1714
+ describeRoute({
1715
+ summary: "Read the usage-reporting passes this deployment has run.",
1716
+ verification: "control-plane",
1717
+ scopes: [PAYMENTS_USAGE_READ_SCOPE],
1718
+ responses: { 200: PaymentsAdminUsageRunsResponse },
1719
+ }),
1720
+ requireControlPlane(PAYMENTS_USAGE_READ_SCOPE),
1721
+ validate("query", AdminUsageRunsQuery),
1722
+ async (c) => {
1723
+ const query = c.req.valid("query");
1724
+ const page = await listUsageRuns(database(c), query);
1725
+ await recordRead(c, PaymentsAuditActions.usageRunsRead, null, {
1726
+ returned: page.items.length,
1727
+ resumed: query.cursor !== undefined,
1728
+ });
1729
+ return c.json(
1730
+ {
1731
+ runs: page.items.map(adminUsageRunView),
1732
+ nextCursor: page.nextCursor,
1733
+ } satisfies PaymentsAdminUsageRunsResponse,
1734
+ 200,
1735
+ );
1736
+ },
1737
+ );
1738
+
1581
1739
  /**
1582
1740
  * CONTROL PLANE WRITE. Start a reconciliation pass now.
1583
1741
  *
@@ -1745,11 +1903,24 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1745
1903
  requireAuth(),
1746
1904
  async (c) => {
1747
1905
  const subject = await resolvePaymentsSubject(c, seam);
1748
- if (subject === undefined) {
1749
- return c.json({ entitlements: [] } satisfies PaymentsEntitlementsResponse, 200);
1906
+ const now = clock();
1907
+ // The allowances ride beside the keys, resolved exactly as `quota(c, name)` resolves them — the floor
1908
+ // for a caller acting for nobody, never an error and never unlimited.
1909
+ const db = subject === undefined ? undefined : paymentsDatabase(database(c));
1910
+ const input = await allowanceInputFor(db, config, subject, now);
1911
+ const resolved = resolveAllowances(input);
1912
+ const allowances = {
1913
+ quotas: Object.fromEntries(resolved.quotas.map((entry) => [entry.name, entry.effective.value])),
1914
+ features: Object.fromEntries(resolved.features.map((entry) => [entry.name, entry.effective.value])),
1915
+ };
1916
+ if (subject === undefined || db === undefined) {
1917
+ return c.json({ entitlements: [], ...allowances } satisfies PaymentsEntitlementsResponse, 200);
1750
1918
  }
1751
- const entitlements = await resolveEntitlements(paymentsDatabase(database(c)), subject, clock());
1752
- return c.json({ entitlements: entitlements.map(entitlementView) } satisfies PaymentsEntitlementsResponse, 200);
1919
+ const entitlements = await resolveEntitlements(db, subject, now);
1920
+ return c.json(
1921
+ { entitlements: entitlements.map(entitlementView), ...allowances } satisfies PaymentsEntitlementsResponse,
1922
+ 200,
1923
+ );
1753
1924
  },
1754
1925
  );
1755
1926
 
@@ -1950,6 +2121,7 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
1950
2121
  {
1951
2122
  providerProductId: sku,
1952
2123
  subscription: entry.product.type === "subscription",
2124
+ reported: entry.product.billing?.kind === "reported",
1953
2125
  // The pair, so the rail stamps `encodeSubjectReference(subject)` into the checkout it creates and
1954
2126
  // the webhook that follows already names a holder this server chose.
1955
2127
  subject,
@@ -2290,9 +2462,22 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
2290
2462
  // `payments/provider_unavailable` instead, so a screen distinguishes the two.
2291
2463
  if (standing === undefined) return c.json({ subscription: null } satisfies PaymentsSubscriptionResponse, 200);
2292
2464
 
2465
+ // The last count reported for a quantity-billed product, from the subscription's own report rows. A
2466
+ // flat-priced product has none, which reads as null rather than absent: this Worker can say.
2467
+ const subscriptionId = target.purchase.originalTransactionId;
2468
+ const last =
2469
+ subscriptionId === null
2470
+ ? undefined
2471
+ : (
2472
+ await lastReports(database(c), [{ rail: target.purchase.rail, providerSubscriptionId: subscriptionId }])
2473
+ ).get(`${target.purchase.rail}:${subscriptionId}`);
2293
2474
  return c.json(
2294
2475
  {
2295
- subscription: subscriptionView(target.purchase.productId, standing),
2476
+ subscription: {
2477
+ ...subscriptionView(target.purchase.productId, standing),
2478
+ reportedQuantity: last?.quantity ?? null,
2479
+ reportedAt: last?.reportedAt.toISOString() ?? null,
2480
+ },
2296
2481
  } satisfies PaymentsSubscriptionResponse,
2297
2482
  200,
2298
2483
  );
@@ -2972,6 +3157,175 @@ export function registerPaymentsRoutes(options: PaymentsRoutesOptions): (app: Ho
2972
3157
  );
2973
3158
  },
2974
3159
  );
3160
+
3161
+ /**
3162
+ * The billing-kind check every override write shares, refused exactly as a grant refuses it. An override
3163
+ * keyed on a kind no read path resolves would shade nobody's numbers and answer 200.
3164
+ */
3165
+ function requireBilledKind(subjectType: PaymentsSubjectType): void {
3166
+ if (subjectType === config.billingSubject) return;
3167
+ throw new ValidationError({
3168
+ message: `This project bills ${config.billingSubject}s, not ${subjectType}s.`,
3169
+ action: "Send `subjectType` as the kind this project bills, or change `billingSubject` in pithy.config.ts.",
3170
+ detail: `An override for a ${subjectType} here writes a row keyed on a kind no read path resolves, so it would shade nobody's allowances and the table would say otherwise.`,
3171
+ });
3172
+ }
3173
+
3174
+ /** What every override write answers. */
3175
+ function overrideResponse(subject: PaymentsSubject, change: OverrideChange): PaymentsOverrideResponse {
3176
+ return {
3177
+ ...subject,
3178
+ override: adminOverrideView(change.after),
3179
+ version: overrideVersion(change.after),
3180
+ };
3181
+ }
3182
+
3183
+ /**
3184
+ * The audit event every override write emits — the subject, the mode, the before and the after, and the
3185
+ * reason verbatim. Severity `warning`, as a comp is: nothing else here changes what a customer may have
3186
+ * with no money moving.
3187
+ */
3188
+ async function emitOverride(
3189
+ c: Context<PithyHonoEnv>,
3190
+ action: PaymentsAuditAction,
3191
+ subject: PaymentsSubject,
3192
+ mode: "patch" | "unrestricted" | "clear",
3193
+ reason: string | null,
3194
+ change: OverrideChange,
3195
+ ): Promise<void> {
3196
+ const caller = controlPlaneCaller(c);
3197
+ await c.var.emit({
3198
+ action,
3199
+ outcome: "success",
3200
+ severity: "warning",
3201
+ actorType: "control-plane",
3202
+ actorId: caller.subject,
3203
+ resourceType: "entitlement_override",
3204
+ resourceId: encodeSubjectReference(subject),
3205
+ metadata: {
3206
+ connectionId: caller.connectionId,
3207
+ subjectType: subject.subjectType,
3208
+ subjectId: subject.subjectId,
3209
+ mode,
3210
+ reason,
3211
+ before: adminOverrideView(change.before),
3212
+ after: adminOverrideView(change.after),
3213
+ },
3214
+ });
3215
+ }
3216
+
3217
+ /**
3218
+ * CONTROL PLANE. Pin a negotiated number or switch for one subject.
3219
+ *
3220
+ * **A merge by name, never a replace.** Only the names sent change; every other pin stands and every name
3221
+ * never pinned keeps tracking the plan, so an upgrade still reaches a customer whose email allowance was
3222
+ * negotiated. **Version-checked**: the body names the version it read, and a set behind the row is
3223
+ * `payments/override_stale` with nothing written. **Bounded**: a number past a declared `overrideMax` is a
3224
+ * 400 naming the limit. **Explained**: `reason` is required and the audit event carries it.
3225
+ *
3226
+ * It does not set `unrestricted`, and a body that tries is a 400 rather than a field quietly dropped:
3227
+ * that is the other route, behind its own scope.
3228
+ */
3229
+ app.post(
3230
+ `${base}/entitlements/overrides`,
3231
+ describeRoute({
3232
+ summary: "Pin quotas and features for one subject.",
3233
+ verification: "control-plane",
3234
+ scopes: [PAYMENTS_OVERRIDE_SET_SCOPE],
3235
+ responses: { 200: PaymentsOverrideResponse },
3236
+ }),
3237
+ requireControlPlane(PAYMENTS_OVERRIDE_SET_SCOPE),
3238
+ validate("json", OverrideSetRequest),
3239
+ async (c) => {
3240
+ const input = c.req.valid("json");
3241
+ requireBilledKind(input.subjectType);
3242
+ const subject: PaymentsSubject = { subjectType: input.subjectType, subjectId: input.subjectId };
3243
+ const change = await setOverride(
3244
+ database(c),
3245
+ config,
3246
+ {
3247
+ subject,
3248
+ version: input.version,
3249
+ reason: input.reason,
3250
+ ...(input.quotas ? { quotas: input.quotas } : {}),
3251
+ ...(input.features ? { features: input.features } : {}),
3252
+ },
3253
+ { now: clock() },
3254
+ );
3255
+ await emitOverride(c, PaymentsAuditActions.overrideSet, subject, "patch", input.reason, change);
3256
+ return c.json(overrideResponse(subject, change) satisfies PaymentsOverrideResponse, 200);
3257
+ },
3258
+ );
3259
+
3260
+ /**
3261
+ * CONTROL PLANE. Grant one subject the whole product, or take it back.
3262
+ *
3263
+ * **Its own route and its own scope**, because it is the largest grant the kit has and the only one whose
3264
+ * reach grows by itself as names are declared: a credential that may raise one email cap must not be able
3265
+ * to do this. Never bounded by `overrideMax` — being unbounded is the point. It grants no entitlement key:
3266
+ * a subject holding nothing is still refused at every gate.
3267
+ */
3268
+ app.post(
3269
+ `${base}/entitlements/overrides/unrestricted`,
3270
+ describeRoute({
3271
+ summary: "Turn unrestricted on or off for one subject.",
3272
+ verification: "control-plane",
3273
+ scopes: [PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE],
3274
+ responses: { 200: PaymentsOverrideResponse },
3275
+ }),
3276
+ requireControlPlane(PAYMENTS_OVERRIDE_UNRESTRICTED_SCOPE),
3277
+ validate("json", OverrideUnrestrictedRequest),
3278
+ async (c) => {
3279
+ const input = c.req.valid("json");
3280
+ requireBilledKind(input.subjectType);
3281
+ const subject: PaymentsSubject = { subjectType: input.subjectType, subjectId: input.subjectId };
3282
+ const change = await setUnrestricted(
3283
+ database(c),
3284
+ { subject, version: input.version, reason: input.reason, unrestricted: input.unrestricted },
3285
+ { now: clock() },
3286
+ );
3287
+ await emitOverride(c, PaymentsAuditActions.overrideSet, subject, "unrestricted", input.reason, change);
3288
+ return c.json(overrideResponse(subject, change) satisfies PaymentsOverrideResponse, 200);
3289
+ },
3290
+ );
3291
+
3292
+ /**
3293
+ * CONTROL PLANE. Unpin names for one subject, or clear its override.
3294
+ *
3295
+ * **Idempotent**: a subject with no override answers 200 with nothing changed — the state the caller asked
3296
+ * for — and writes no audit row, because nothing moved. A name unpinned resolves from the plan again.
3297
+ */
3298
+ app.post(
3299
+ `${base}/entitlements/overrides/clear`,
3300
+ describeRoute({
3301
+ summary: "Unpin allowances for one subject, or clear its override.",
3302
+ verification: "control-plane",
3303
+ scopes: [PAYMENTS_OVERRIDE_CLEAR_SCOPE],
3304
+ responses: { 200: PaymentsOverrideResponse },
3305
+ }),
3306
+ requireControlPlane(PAYMENTS_OVERRIDE_CLEAR_SCOPE),
3307
+ validate("json", OverrideClearRequest),
3308
+ async (c) => {
3309
+ const input = c.req.valid("json");
3310
+ requireBilledKind(input.subjectType);
3311
+ const subject: PaymentsSubject = { subjectType: input.subjectType, subjectId: input.subjectId };
3312
+ const change = await clearOverride(
3313
+ database(c),
3314
+ {
3315
+ subject,
3316
+ ...(input.version !== undefined ? { version: input.version } : {}),
3317
+ ...(input.quotas ? { quotas: input.quotas } : {}),
3318
+ ...(input.features ? { features: input.features } : {}),
3319
+ ...(input.reason ? { reason: input.reason } : {}),
3320
+ },
3321
+ { now: clock() },
3322
+ );
3323
+ if (change.before !== undefined) {
3324
+ await emitOverride(c, PaymentsAuditActions.overrideCleared, subject, "clear", input.reason ?? null, change);
3325
+ }
3326
+ return c.json(overrideResponse(subject, change) satisfies PaymentsOverrideResponse, 200);
3327
+ },
3328
+ );
2975
3329
  };
2976
3330
 
2977
3331
  /**