@openreceive/http 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenReceive contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @openreceive/http
+
+Framework-neutral receive-checkout handler. Its normal form requires `service`,
+`authorize`, and the `host` integration. Create bodies never accept payer
+amounts; the host's `amountFor` hook is the only price authority, and the
+commit hook appends a payment-attempt row before the invoice is returned.
+
+This package is ESM-only and requires Node >= 22.
+
+`createHost({ db, amountFor, onPaid })` builds that
+host integration on the library-owned payment repository inside the host
+application's existing database (pg, node:sqlite, better-sqlite3, or a custom
+adapter). The library owns attempt selection, per-reference commit locking,
+write-once settlement with first-attempt-only fulfillment, and the
+`pending → settled | expired | failed | attention` reconciliation state
+machine (`attention` reads as `pending` on the wire; operators see it only in
+`openreceive_payments.status`). `onPaid` is the settlement hook in both modes: with `db` it receives
+`PaymentSettlement` (`reference` plus a `query` that runs inside the
+settlement transaction); with a custom repository it receives the raw
+`SettlementEvent` (`paymentHash`, `paidAt`, `details`). Settlement
+piggybacks on mounted routes by default through the durable `openreceive_meta`
+gate (`opportunisticReconcile: false` disables, `{ minIntervalSeconds }`
+tunes); `startNotificationWorker` is the optional
+listen-plus-reconcile worker process. A custom `PaymentRepository`
+via the `payments` option is the advanced escape hatch.
+
+It reuses one live attempt per rail, permits new attempts after expiry, and
+verifies the `payment_hash` selector belongs to the authorized order. Committed
+retries use the stored safe checkout snapshot. `swapData` is never serialized
+into an HTTP response. OpenReceive never requires a separate database or Redis.
+
+This is the home of the full host-integration surface. The framework adapters
+(`@openreceive/express`, `@openreceive/fastify`, `@openreceive/next`) re-export
+only a curated slice — the handler/stack factories, error surface, notification
+worker, and their options/context/hook types — so anything deeper imports from
+here (`npm run check:public-api` pins both surfaces):
+
+- Handler and stack: `createHttpHandler`, `createStack`,
+  their options types, and `mapHostRouteError` / `HttpError` /
+  `HostError`.
+- Host integration: `createHost`, the SQL repository
+  (`createSqlPayments`, `paymentsSchemaSql`), the
+  `PaymentRepository` contract types, and the settlement hook
+  contexts above.
+- Reconciliation: `maybeReconcilePayments` (the durable gate pass),
+  `reconcileHostPayments`, `startReconciler`, and the shared
+  constants (`OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS`,
+  `OPENRECEIVE_RECONCILE_BATCH_SIZE`, scan bounds).
+- Rate limiting: `createIpRateLimit`, `resolveClientIp`, and
+  `IpRateLimitConfig` behind the handler's `rateLimiting` /
+  `rateLimitHook` options.
+- Generated wire types: the snake_case `Wire*` request/response body
+  types (`WireCheckout`, `WireCreateCheckoutRequest`,
+  `WirePaymentCheck`, `WireError`, …), generated from the
+  OpenAPI contract. The adapters re-export these too.
+
+See the root README, the storage guide, and the OpenAPI contract.