@hearthkit/payments 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthkit/payments",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Stripe subscriptions and one-time purchases: catalog sync, hosted checkout, the hosted customer portal, and the webhook handler",
   "license": "MIT",
   "homepage": "https://github.com/chrisdevelops/hearthkit/tree/main/packages/payments",
@@ -16,8 +16,8 @@
       "default": "./src/index.ts"
     },
     "./payments-contract": {
-      "types": "./src/payments-contract.ts",
-      "default": "./src/payments-contract.ts"
+      "types": "./src/payments-contract-entry.ts",
+      "default": "./src/payments-contract-entry.ts"
     }
   },
   "files": [
@@ -33,9 +33,9 @@
     "drizzle-orm": "0.45.2",
     "stripe": "22.6.1",
     "zod": "4.4.3",
-    "@hearthkit/auth": "0.3.0",
-    "@hearthkit/config": "0.3.0",
-    "@hearthkit/db": "0.3.0"
+    "@hearthkit/config": "0.4.0",
+    "@hearthkit/db": "0.4.0",
+    "@hearthkit/auth": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/src/handle-stripe-webhook-signature.test.ts

@@ -18,6 +18,8 @@ import {
 import {
   gatePaymentsCatalog,
   gateWrongStripeWebhookSecret,
+  stripeWrongSchemeSignatureMessage,
+  stripeWrongSecretSignatureMessagePrefix,
   uniqueGateBillingContactEmail,
   uniqueGateBillingReferenceId,
   uniqueGatePaymentsCatalogNames,
@@ -30,8 +32,6 @@ import {
 import {
   handleStripeWebhookResultSchema,
   stripeSignatureHeaderName,
-  stripeWrongSchemeSignatureMessage,
-  stripeWrongSecretSignatureMessagePrefix,
   type PaymentsClient,
 } from './payments-contract.ts'
 
@@ -137,20 +137,11 @@ describe('payments-webhook-signature-invalid', () => {
     // for payload.` is the wrong-secret message, and `No signatures found with expected scheme` is
     // thrown one line away for a header carrying no v1 entry, which is a different cause. A
     // substring test on `No signatures found` would satisfy both, so this matches the whole prefix
-    // and then proves the decoy is not what came back.
+    // and then proves the decoy is not what came back. Both strings are read off stripe@22.6.1 and
+    // live in the fixtures: their only reader is this gate, so they are not public surface.
     const stripeFailureDetail = failure.stripeFailureDetail ?? ''
-    expect(stripeFailureDetail).toContain(
-      expectContractStringExport(
-        stripeWrongSecretSignatureMessagePrefix,
-        'stripeWrongSecretSignatureMessagePrefix',
-      ),
-    )
-    expect(stripeFailureDetail).not.toContain(
-      expectContractStringExport(
-        stripeWrongSchemeSignatureMessage,
-        'stripeWrongSchemeSignatureMessage',
-      ),
-    )
+    expect(stripeFailureDetail).toContain(stripeWrongSecretSignatureMessagePrefix)
+    expect(stripeFailureDetail).not.toContain(stripeWrongSchemeSignatureMessage)
 
     // StripeSignatureVerificationError carries the raw webhook body on `.payload`, so it holds
     // whatever customer data the event held. The detail quotes the message and never the payload.

package/src/index.ts

@@ -27,164 +27,37 @@ export { verifyPaymentsTablesExist } from './verify-payments-tables-exist.ts'
 /** The Drizzle table map, always carrying all three tables whatever the organizations flag is. */
 export { hearthkitPaymentsDrizzleSchema } from './hearthkit-payments-drizzle-schema.ts'
 
-/** Contract values: the unique literal prefix every returned failure message starts with. */
+/** Contract values: this package's env fragment, the failure union every function returns, and the catalog schema an app parses payments-catalog.ts with. */
 export {
-  paymentsCatalogInvalidErrorPrefix,
-  paymentsCustomerNotFoundErrorPrefix,
-  paymentsDatabaseUnavailableErrorPrefix,
-  paymentsInputInvalidErrorPrefix,
-  paymentsPriceNotFoundErrorPrefix,
-  paymentsRequestFailedErrorPrefix,
-  paymentsStripeUnauthorizedErrorPrefix,
-  paymentsStripeUnreachableErrorPrefix,
-  paymentsWebhookSignatureInvalidErrorPrefix,
-} from './payments-contract.ts'
-
-/** Contract values: the Stripe literals this package matches by exact equality, each read off stripe@22.6.1 rather than from documentation. */
-export {
-  stripeForbiddenHttpStatus,
-  stripeOneTimeCheckoutMode,
-  stripeOneTimePriceType,
-  stripeParsedBodySignatureMessagePrefix,
-  stripeRecurringPriceType,
-  stripeSignatureHeaderName,
-  stripeSignatureScheme,
-  stripeSignatureToleranceSeconds,
-  stripeSubscriptionCheckoutMode,
-  stripeUnauthorizedHttpStatus,
-  stripeWrongSchemeSignatureMessage,
-  stripeWrongSecretSignatureMessagePrefix,
-} from './payments-contract.ts'
-
-/** Contract values: the Stripe metadata keys createCheckoutSession writes and the webhook handler reads back. */
-export {
-  hearthkitBillingReferenceMetadataKey,
-  hearthkitBillingScopeMetadataKey,
-  hearthkitPriceNameMetadataKey,
-  hearthkitQuantityMetadataKey,
-  hearthkitStripePriceIdMetadataKey,
-} from './payments-contract.ts'
-
-/** Contract values: the name lists, status lists and limits an app and a gate compare against. */
-export {
-  defaultCheckoutQuantity,
-  handledStripeWebhookEventTypeSchema,
-  handledStripeWebhookEventTypes,
-  hearthkitPaymentsTableNameSchema,
-  hearthkitPaymentsTableNames,
-  maximumPaymentsPriceNameLength,
-  maximumPaymentsProductNameLength,
-  paymentsActiveSubscriptionStatuses,
-  paymentsDatabaseUnavailableCauseCodes,
-  paymentsKnownSubscriptionStatuses,
-} from './payments-contract.ts'
-
-/** Contract values: this package's env fragment and the two secret schemas it is built from. */
-export {
-  paymentsEnvSchemaFragment,
-  stripeSecretKeySchema,
-  stripeWebhookSecretSchema,
-} from './payments-contract.ts'
-
-/** Contract values: the branded vocabulary schemas, so an app can parse an untrusted value before calling anything here. */
-export {
-  billingContactEmailSchema,
-  billingReferenceIdSchema,
-  billingScopeSchema,
-  paymentsCurrencyCodeSchema,
-  paymentsCustomerIdSchema,
-  paymentsPriceNameSchema,
-  paymentsProductNameSchema,
-  paymentsPurchaseIdSchema,
-  paymentsQuantitySchema,
-  paymentsRecurringIntervalSchema,
-  paymentsRedirectUrlSchema,
-  paymentsStripeApiBaseUrlSchema,
-  paymentsSubscriptionIdSchema,
-  paymentsSubscriptionStatusSchema,
-  paymentsUnitAmountMinorUnitsSchema,
-  stripeCheckoutSessionIdSchema,
-  stripeCustomerIdSchema,
-  stripeEventIdSchema,
-  stripePaymentIntentIdSchema,
-  stripePriceIdSchema,
-  stripeProductIdSchema,
-  stripeSubscriptionIdSchema,
-} from './payments-contract.ts'
-
-/** Contract values: the catalog schemas an app validates payments-catalog.ts with, and the three row shapes this package reports. */
-export {
-  paymentsCatalogPriceSchema,
-  paymentsCatalogProductSchema,
   paymentsCatalogSchema,
-  paymentsCustomerSchema,
-  paymentsOneTimeCatalogPriceSchema,
-  paymentsPurchaseSchema,
-  paymentsSubscriptionCatalogPriceSchema,
-  paymentsSubscriptionSchema,
-} from './payments-contract.ts'
-
-/** Contract values: each failure variant's schema, the discriminator enums, and the union of all nine. */
-export {
-  paymentsCatalogInvalidFailureSchema,
-  paymentsCatalogIssueKindSchema,
-  paymentsCatalogIssueSchema,
-  paymentsCustomerNotFoundFailureSchema,
-  paymentsDatabaseUnavailableFailureSchema,
+  paymentsEnvSchemaFragment,
   paymentsFailureSchema,
-  paymentsInputInvalidFailureSchema,
-  paymentsInvalidFieldNameSchema,
-  paymentsPriceNotFoundFailureSchema,
-  paymentsRequestFailedFailureSchema,
-  paymentsStripeUnauthorizedFailureSchema,
-  paymentsStripeUnreachableFailureSchema,
-  paymentsWebhookSignatureInvalidFailureSchema,
-  priceLookupFailureSchema,
-  webhookSignatureFailureReasonSchema,
-} from './payments-contract.ts'
-
-/** Contract values: the runtime checks for the three structural values this package takes in or hands back. */
-export {
-  paymentsClientSchema,
-  paymentsDrizzleClientSchema,
-  paymentsRequestHeadersSchema,
 } from './payments-contract.ts'
 
-/** Contract values: each function's options, success-only and full result schemas, so a narrowed result can be validated without rebuilding the schema. */
+/** Contract values: the full result schema of each of the eight functions, for validating a value that crossed a process or network boundary. */
 export {
-  createCheckoutSessionOptionsSchema,
   createCheckoutSessionResultSchema,
-  createCustomerPortalSessionOptionsSchema,
   createCustomerPortalSessionResultSchema,
-  createPaymentsClientOptionsSchema,
   createPaymentsClientResultSchema,
-  handleStripeWebhookOptionsSchema,
   handleStripeWebhookResultSchema,
-  listPaymentsPurchasesOptionsSchema,
   listPaymentsPurchasesResultSchema,
-  paymentsCatalogSyncedSchema,
-  paymentsCheckoutSessionCreatedSchema,
-  paymentsClientCreatedSchema,
-  paymentsPortalSessionCreatedSchema,
-  paymentsPriceSyncActionSchema,
-  paymentsPurchasesListedSchema,
-  paymentsSubscriptionAbsentSchema,
-  paymentsSubscriptionFoundSchema,
-  paymentsSyncedPriceSchema,
-  paymentsTablesMissingSchema,
-  paymentsTablesPresentSchema,
-  paymentsWebhookIgnoredReasonSchema,
-  paymentsWebhookIgnoredSchema,
-  paymentsWebhookOutcomeSchema,
-  paymentsWebhookProcessedSchema,
-  readPaymentsSubscriptionOptionsSchema,
   readPaymentsSubscriptionResultSchema,
-  syncPaymentsCatalogOptionsSchema,
   syncPaymentsCatalogResultSchema,
-  verifyPaymentsTablesExistOptionsSchema,
   verifyPaymentsTablesExistResultSchema,
 } from './payments-contract.ts'
 
+/** Contract values: the table names drizzle-kit is pointed at, and the per-price row shape a sync run reports. */
+export { hearthkitPaymentsTableNames, paymentsSyncedPriceSchema } from './payments-contract.ts'
+
+/** Contract values: the five wire constants an app needs to sign a webhook body and read Stripe metadata back. */
+export {
+  hearthkitBillingReferenceMetadataKey,
+  hearthkitPriceNameMetadataKey,
+  hearthkitQuantityMetadataKey,
+  hearthkitStripePriceIdMetadataKey,
+  stripeSignatureHeaderName,
+} from './payments-contract.ts'
+
 /** Contract types: the branded vocabulary and the two scope words billing is keyed on. */
 export type {
   BillingContactEmail,

package/src/payments-contract-entry.ts

@@ -0,0 +1,124 @@
+/**
+ * The ./payments-contract subpath of @hearthkit/payments: a named re-export of the eighteen contract
+ * values that live in payments-contract.ts and every public type, and nothing that reaches an
+ * implementation module. It exists because @hearthkit/cli imports paymentsFailureSchema and
+ * paymentsSyncedPriceSchema at runtime (plus the PaymentsFailure, PaymentsCatalog and
+ * PaymentsEnvValues types, and paymentsCatalogSchema in its fixture) and templates/app imports
+ * hearthkitPaymentsTableNames and the five wire constants, while the `.` entry imports stripe,
+ * drizzle-orm/pg-core and the Drizzle table definitions, none of which the cli's `hearthkit payments
+ * sync` or templates/app's drizzle.config.ts should have to load to read a schema. This file and
+ * payments-contract.ts import only zod at runtime, so either loads under bare node with no side
+ * effect.
+ */
+
+/** Contract values: this package's env fragment, the failure union every function returns, and the catalog schema an app parses payments-catalog.ts with. */
+export {
+  paymentsCatalogSchema,
+  paymentsEnvSchemaFragment,
+  paymentsFailureSchema,
+} from './payments-contract.ts'
+
+/** Contract values: the full result schema of each of the eight functions, for validating a value that crossed a process or network boundary. */
+export {
+  createCheckoutSessionResultSchema,
+  createCustomerPortalSessionResultSchema,
+  createPaymentsClientResultSchema,
+  handleStripeWebhookResultSchema,
+  listPaymentsPurchasesResultSchema,
+  readPaymentsSubscriptionResultSchema,
+  syncPaymentsCatalogResultSchema,
+  verifyPaymentsTablesExistResultSchema,
+} from './payments-contract.ts'
+
+/** Contract values: the table names drizzle-kit is pointed at, and the per-price row shape a sync run reports. */
+export { hearthkitPaymentsTableNames, paymentsSyncedPriceSchema } from './payments-contract.ts'
+
+/** Contract values: the five wire constants an app needs to sign a webhook body and read Stripe metadata back. */
+export {
+  hearthkitBillingReferenceMetadataKey,
+  hearthkitPriceNameMetadataKey,
+  hearthkitQuantityMetadataKey,
+  hearthkitStripePriceIdMetadataKey,
+  stripeSignatureHeaderName,
+} from './payments-contract.ts'
+
+/** Contract types: the branded vocabulary and the two scope words billing is keyed on. */
+export type {
+  BillingContactEmail,
+  BillingReferenceId,
+  BillingReferenceOwnerId,
+  BillingScope,
+  HandledStripeWebhookEventType,
+  HearthkitPaymentsTableName,
+  PaymentsCurrencyCode,
+  PaymentsCustomerId,
+  PaymentsPriceName,
+  PaymentsProductName,
+  PaymentsPurchaseId,
+  PaymentsRecurringInterval,
+  PaymentsSubscriptionId,
+  StripeCheckoutSessionId,
+  StripeCustomerId,
+  StripeEventId,
+  StripePaymentIntentId,
+  StripePriceId,
+  StripeProductId,
+  StripeSecretKey,
+  StripeSubscriptionId,
+  StripeWebhookSecret,
+} from './payments-contract.ts'
+
+/** Contract types: the env values, the catalog, the three records this package reports, and the Drizzle table map. */
+export type {
+  HearthkitPaymentsDrizzleSchema,
+  PaymentsCatalog,
+  PaymentsCatalogPrice,
+  PaymentsCatalogProduct,
+  PaymentsClient,
+  PaymentsCustomer,
+  PaymentsEnvValues,
+  PaymentsPurchase,
+  PaymentsSubscription,
+  PaymentsSyncedPrice,
+} from './payments-contract.ts'
+
+/** Contract types: the failure union and every discriminator carried on one. */
+export type {
+  PaymentsCatalogIssue,
+  PaymentsCatalogIssueKind,
+  PaymentsFailure,
+  PaymentsInvalidFieldName,
+  PaymentsPriceSyncAction,
+  PaymentsWebhookIgnoredReason,
+  PaymentsWebhookOutcome,
+  PriceLookupFailure,
+  WebhookSignatureFailureReason,
+} from './payments-contract.ts'
+
+/** Contract types: the option, result and function shapes of every function above. */
+export type {
+  CreateCheckoutSession,
+  CreateCheckoutSessionOptions,
+  CreateCheckoutSessionResult,
+  CreateCustomerPortalSession,
+  CreateCustomerPortalSessionOptions,
+  CreateCustomerPortalSessionResult,
+  CreatePaymentsClient,
+  CreatePaymentsClientOptions,
+  CreatePaymentsClientResult,
+  HandleStripeWebhook,
+  HandleStripeWebhookOptions,
+  HandleStripeWebhookResult,
+  ListPaymentsPurchases,
+  ListPaymentsPurchasesOptions,
+  ListPaymentsPurchasesResult,
+  ReadPaymentsSubscription,
+  ReadPaymentsSubscriptionOptions,
+  ReadPaymentsSubscriptionResult,
+  SyncPaymentsCatalog,
+  SyncPaymentsCatalogOptions,
+  SyncPaymentsCatalogResult,
+  VerifyPaymentsTablesExist,
+  VerifyPaymentsTablesExistOptions,
+  VerifyPaymentsTablesExistResult,
+} from './payments-contract.ts'

package/src/payments-contract.ts

@@ -34,27 +34,6 @@ export const paymentsRequestFailedErrorPrefix = 'hearthkit payments request fail
 /** HTTP header Stripe signs a webhook delivery with; this package reads it off the request headers so the name is spelled once. */
 export const stripeSignatureHeaderName = 'stripe-signature'
 
-/** Signature scheme inside that header, read off stripe@22.6.1's EXPECTED_SCHEME; every entry this package verifies is a v1 entry. */
-export const stripeSignatureScheme = 'v1'
-
-/** Seconds a signed webhook stays acceptable, read off stripe@22.6.1's DEFAULT_TOLERANCE; an older signature is rejected as invalid. */
-export const stripeSignatureToleranceSeconds = 300
-
-// Measured in stripe@22.6.1's esm/Webhooks.js:184. THE DECOY IS ONE LINE AWAY IN THE SAME FILE:
-// `No signatures found with expected scheme` (line 130) is thrown when the header parses but carries
-// no v1 entry, which is a DIFFERENT cause. A gate matching the substring `No signatures found`
-// satisfies both, so a wrong-secret gate must match this whole prefix and not the shared words.
-/** Opening words of the message stripe throws when the signing secret is wrong; the value a wrong-secret gate matches on. */
-export const stripeWrongSecretSignatureMessagePrefix =
-  'No signatures found matching the expected signature for payload.'
-
-/** Message stripe throws when the header parses but carries no v1 entry; named only so nobody mistakes it for the wrong-secret one. */
-export const stripeWrongSchemeSignatureMessage = 'No signatures found with expected scheme'
-
-/** Opening words of the message stripe throws when a parsed object was passed instead of the raw request body. */
-export const stripeParsedBodySignatureMessagePrefix =
-  'Webhook payload must be provided as a string or a Buffer'
-
 /** HTTP status Stripe answers with when the API key is wrong or revoked; mapped to payments-stripe-unauthorized. */
 export const stripeUnauthorizedHttpStatus = 401
 
@@ -695,8 +674,8 @@ export type CreatePaymentsClientOptions = {
   stripeApiBaseUrl?: string
 }
 
-/** Success shape of createPaymentsClient; the flag and the scope are echoed back so a caller holding the result knows which mode it built. */
-export const paymentsClientCreatedSchema = z.object({
+/** Success shape of createPaymentsClient; module-private, reachable only through the result union below. The flag and the scope are echoed back so a caller holding the result knows which mode it built. */
+const paymentsClientCreatedSchema = z.object({
   kind: z.literal('payments-client-created'),
   paymentsClient: paymentsClientSchema,
   organizationsEnabled: z.boolean(),
@@ -747,8 +726,8 @@ export type SyncPaymentsCatalogOptions = {
 // stripeLivemode is read off the Stripe object the API answered with, whose own generated type says
 // it is true in live mode and false in test mode. It is here so a gate can refuse to touch a live
 // account without matching on an API key prefix, which is a constant nothing offline can verify.
-/** Success shape of syncPaymentsCatalog; stripeLivemode is the measured guard a gate asserts false before creating anything. */
-export const paymentsCatalogSyncedSchema = z.object({
+/** Success shape of syncPaymentsCatalog; module-private. stripeLivemode is the measured guard a gate asserts false before creating anything. */
+const paymentsCatalogSyncedSchema = z.object({
   kind: z.literal('payments-catalog-synced'),
   syncedPrices: z.array(paymentsSyncedPriceSchema).min(1),
   stripeLivemode: z.boolean(),
@@ -790,8 +769,8 @@ export type CreateCheckoutSessionOptions = {
   cancelUrl: string
 }
 
-/** Success shape of createCheckoutSession; checkoutUrl is the hosted page to redirect the buyer to. */
-export const paymentsCheckoutSessionCreatedSchema = z.object({
+/** Success shape of createCheckoutSession; module-private. checkoutUrl is the hosted page to redirect the buyer to. */
+const paymentsCheckoutSessionCreatedSchema = z.object({
   kind: z.literal('payments-checkout-session-created'),
   stripeCheckoutSessionId: stripeCheckoutSessionIdSchema,
   checkoutUrl: z.url(),
@@ -828,8 +807,8 @@ export type CreateCustomerPortalSessionOptions = {
   returnUrl: string
 }
 
-/** Success shape of createCustomerPortalSession; portalUrl is short-lived, so it is redirected to rather than stored. */
-export const paymentsPortalSessionCreatedSchema = z.object({
+/** Success shape of createCustomerPortalSession; module-private. portalUrl is short-lived, so it is redirected to rather than stored. */
+const paymentsPortalSessionCreatedSchema = z.object({
   kind: z.literal('payments-portal-session-created'),
   portalUrl: z.url(),
   stripeCustomerId: stripeCustomerIdSchema,
@@ -899,16 +878,16 @@ export type HandleStripeWebhookOptions = {
   requestHeaders: Headers
 }
 
-/** Result shape when the delivery was acted on; a replay of the same event writes the same row and moves no count. */
-export const paymentsWebhookProcessedSchema = z.object({
+/** Result shape when the delivery was acted on; module-private. A replay of the same event writes the same row and moves no count. */
+const paymentsWebhookProcessedSchema = z.object({
   kind: z.literal('payments-webhook-processed'),
   stripeEventId: stripeEventIdSchema,
   stripeEventType: z.string().min(1),
   webhookOutcome: paymentsWebhookOutcomeSchema,
 })
 
-/** Result shape when the delivery was verified but not acted on; a successful answer, not a failure, because most events are none of our business. */
-export const paymentsWebhookIgnoredSchema = z.object({
+/** Result shape when the delivery was verified but not acted on; module-private. A successful answer, not a failure, because most events are none of our business. */
+const paymentsWebhookIgnoredSchema = z.object({
   kind: z.literal('payments-webhook-ignored'),
   stripeEventId: stripeEventIdSchema,
   stripeEventType: z.string().min(1),
@@ -942,14 +921,14 @@ export type ReadPaymentsSubscriptionOptions = {
   billingReferenceId: string
 }
 
-/** Result shape when a subscription row exists; the row is returned whatever its status, and the caller decides what counts as entitled. */
-export const paymentsSubscriptionFoundSchema = z.object({
+/** Result shape when a subscription row exists; module-private. The row is returned whatever its status, and the caller decides what counts as entitled. */
+const paymentsSubscriptionFoundSchema = z.object({
   kind: z.literal('payments-subscription-found'),
   paymentsSubscription: paymentsSubscriptionSchema,
 })
 
-/** Result shape when the reference has no subscription row at all; nobody having a subscription is a normal answer, not a failure. */
-export const paymentsSubscriptionAbsentSchema = z.object({
+/** Result shape when the reference has no subscription row at all; module-private. Nobody having a subscription is a normal answer, not a failure. */
+const paymentsSubscriptionAbsentSchema = z.object({
   kind: z.literal('payments-subscription-absent'),
 })
 
@@ -980,8 +959,8 @@ export type ListPaymentsPurchasesOptions = {
   billingReferenceId: string
 }
 
-/** Success shape of listPaymentsPurchases; an empty array is a success, because "has bought nothing" is a correct answer. */
-export const paymentsPurchasesListedSchema = z.object({
+/** Success shape of listPaymentsPurchases; module-private. An empty array is a success, because "has bought nothing" is a correct answer. */
+const paymentsPurchasesListedSchema = z.object({
   kind: z.literal('payments-purchases-listed'),
   paymentsPurchases: z.array(paymentsPurchaseSchema),
 })
@@ -1010,14 +989,14 @@ export type VerifyPaymentsTablesExistOptions = {
   drizzleClient: NodePgDatabase<Record<string, unknown>>
 }
 
-/** Result shape when every payments table is present in the public schema, in both user-scoped and org-scoped mode. */
-export const paymentsTablesPresentSchema = z.object({
+/** Result shape when every payments table is present in the public schema; module-private, and true in both user-scoped and org-scoped mode. */
+const paymentsTablesPresentSchema = z.object({
   kind: z.literal('payments-tables-present'),
   presentTableNames: z.array(hearthkitPaymentsTableNameSchema).min(1),
 })
 
-/** Result shape when at least one payments table is absent; this is a successful check reporting a negative answer. */
-export const paymentsTablesMissingSchema = z.object({
+/** Result shape when at least one payments table is absent; module-private, a successful check reporting a negative answer. */
+const paymentsTablesMissingSchema = z.object({
   kind: z.literal('payments-tables-missing'),
   missingTableNames: z.array(hearthkitPaymentsTableNameSchema).min(1),
 })

package/src/payments-env-schema-fragment.test.ts

@@ -3,9 +3,12 @@ import { describe, expect, it } from 'vitest'
 import { expectResultKind } from '../test-fixtures/payments-gate-expectations.ts'
 import {
   readPaymentsPackageManifest,
-  runPaymentsContractUnderBareNode,
+  runPaymentsContractModulesUnderBareNode,
 } from '../test-fixtures/payments-package-entry-points.ts'
 import {
+  hearthkitPaymentsContractSubpathValueExportNames,
+  hearthkitPaymentsEntryValueExportNames,
+  importHearthkitPaymentsContractSubpathNamespace,
   importHearthkitPaymentsNamespace,
   loadHearthkitPaymentsEntry,
 } from '../test-fixtures/hearthkit-payments-entry.ts'
@@ -18,61 +21,6 @@ const completePaymentsEnv = {
   STRIPE_WEBHOOK_SECRET: 'whsec_GateSigningSecretThatIsNotRealEither',
 }
 
-// CONTRACT.md's entry point rule is mechanical: src/index.ts re-exports every value
-// src/payments-contract.ts exports, with no exceptions. So the required list is read off the contract
-// module's own namespace rather than typed out here. A hand-written list would fall behind the day
-// someone forgot to extend it; a derived list cannot.
-//
-// A module namespace carries value exports only. Every `export type` in payments-contract.ts is
-// erased before this file runs, so the types CONTRACT.md also asks the entry point to re-export are
-// outside what this gate can see and are covered by typecheck instead.
-function contractValueExportNames(contractModule: Record<string, unknown>): string[] {
-  return Object.keys(contractModule).toSorted()
-}
-
-// Named in so many words by CONTRACT.md: the nine message prefixes, the env fragment, the failure
-// union, the table name list, the two subscription status lists and the eight per-function result
-// schemas. Spelled out as strings so renaming one in the contract fails this gate loudly, instead of
-// quietly shrinking the derived list above to a set an entry point already satisfies.
-const contractExportNamesTheContractNamesOutright = [
-  'paymentsInputInvalidErrorPrefix',
-  'paymentsCatalogInvalidErrorPrefix',
-  'paymentsPriceNotFoundErrorPrefix',
-  'paymentsCustomerNotFoundErrorPrefix',
-  'paymentsWebhookSignatureInvalidErrorPrefix',
-  'paymentsStripeUnauthorizedErrorPrefix',
-  'paymentsStripeUnreachableErrorPrefix',
-  'paymentsDatabaseUnavailableErrorPrefix',
-  'paymentsRequestFailedErrorPrefix',
-  'paymentsEnvSchemaFragment',
-  'paymentsFailureSchema',
-  'hearthkitPaymentsTableNames',
-  'paymentsKnownSubscriptionStatuses',
-  'paymentsActiveSubscriptionStatuses',
-  'createPaymentsClientResultSchema',
-  'syncPaymentsCatalogResultSchema',
-  'createCheckoutSessionResultSchema',
-  'createCustomerPortalSessionResultSchema',
-  'handleStripeWebhookResultSchema',
-  'readPaymentsSubscriptionResultSchema',
-  'listPaymentsPurchasesResultSchema',
-  'verifyPaymentsTablesExistResultSchema',
-] as const
-
-// Not exported by payments-contract.ts, so the derived list cannot cover them: the eight public
-// functions and the Drizzle table map.
-const entryPointOnlyExportNames = [
-  'createPaymentsClient',
-  'syncPaymentsCatalog',
-  'createCheckoutSession',
-  'createCustomerPortalSession',
-  'handleStripeWebhook',
-  'readPaymentsSubscription',
-  'listPaymentsPurchases',
-  'verifyPaymentsTablesExist',
-  'hearthkitPaymentsDrizzleSchema',
-] as const
-
 describe('paymentsEnvSchemaFragment', () => {
   it('declares two required variables, names both at load when neither is set, treats an empty value as unset, and rejects one carrying whitespace', async () => {
     const { paymentsEnvSchemaFragment } = await loadHearthkitPaymentsEntry()
@@ -140,30 +88,29 @@ describe('paymentsEnvSchemaFragment', () => {
 })
 
 describe('@hearthkit/payments entry point', () => {
-  it('re-exports by name every value payments-contract.ts exports, plus the eight functions and the Drizzle schema', async () => {
+  it('exports exactly the twenty-seven allowlisted values and nothing else, each contract value the one payments-contract.ts already exports', async () => {
     const namespace = await importHearthkitPaymentsNamespace()
     const contractModule = paymentsContract as unknown as Record<string, unknown>
-    const requiredExportNames = contractValueExportNames(contractModule)
-
-    const renamedInTheContract = contractExportNamesTheContractNamesOutright.filter(
-      (exportName) => !requiredExportNames.includes(exportName),
-    )
-    expect(
-      renamedInTheContract,
-      'payments-contract.ts must still export the constants and schemas CONTRACT.md names outright',
-    ).toEqual([])
 
-    // Both lists are compared whole rather than one name at a time, so a failure names every export
-    // that is wrong instead of stopping at the first and hiding the rest behind a rerun.
-    const missingFromTheEntryPoint = requiredExportNames.filter(
-      (exportName) => namespace[exportName] === undefined,
-    )
+    // A module namespace carries value exports only, so every `export type` is already erased here and
+    // the types CONTRACT.md keeps on the entry point are covered by typecheck instead. Both lists are
+    // compared whole rather than name by name, so a failure names every wrong export at once instead
+    // of stopping at the first and hiding the rest behind a rerun.
+    const actualValueExportNames = Object.keys(namespace)
+      .filter((exportName) => namespace[exportName] !== undefined)
+      .toSorted()
     expect(
-      missingFromTheEntryPoint,
-      'src/index.ts must re-export these by name from payments-contract.ts',
-    ).toEqual([])
-
-    const rebuiltInsteadOfReExported = requiredExportNames.filter(
+      actualValueExportNames,
+      'src/index.ts must export exactly the allowlist in CONTRACT.md "Package entry point"',
+    ).toEqual([...hearthkitPaymentsEntryValueExportNames].toSorted())
+
+    // The eighteen contract values must be the identical values payments-contract.ts exports, not a
+    // second copy: an app comparing entry.hearthkitPaymentsTableNames against the subpath's value is
+    // comparing the same thing. The nine prefixes, the Stripe literals and HTTP statuses, the limits,
+    // the branded and record schemas, the options schemas and the eleven per-arm success shapes stay
+    // internal, so they are absent from the list above and a re-export of one of them fails the
+    // whole-list comparison by name.
+    const rebuiltInsteadOfReExported = hearthkitPaymentsContractSubpathValueExportNames.filter(
       (exportName) => namespace[exportName] !== contractModule[exportName],
     )
     expect(
@@ -171,27 +118,62 @@ describe('@hearthkit/payments entry point', () => {
       'these must be the identical value payments-contract.ts exports, not a second copy of it',
     ).toEqual([])
 
-    const missingImplementationExports = entryPointOnlyExportNames.filter(
-      (exportName) => namespace[exportName] === undefined,
-    )
+    // Everything else on the allowlist comes from an implementation module: the eight functions, plus
+    // hearthkitPaymentsDrizzleSchema, which is the Drizzle table map and therefore an object. Whether
+    // it carries the right tables and columns is the schema gate's job, not this one's.
+    const wrongShape = hearthkitPaymentsEntryValueExportNames.filter((exportName) => {
+      const isContractValue = hearthkitPaymentsContractSubpathValueExportNames.includes(
+        exportName as (typeof hearthkitPaymentsContractSubpathValueExportNames)[number],
+      )
+      if (isContractValue) {
+        return false
+      }
+      if (exportName === 'hearthkitPaymentsDrizzleSchema') {
+        return typeof namespace[exportName] !== 'object' || namespace[exportName] === null
+      }
+      return typeof namespace[exportName] !== 'function'
+    })
     expect(
-      missingImplementationExports,
-      'src/index.ts must re-export the public functions and the Drizzle schema by name',
+      wrongShape,
+      'every allowlisted name outside the eighteen contract values must be one of the eight functions, or the Drizzle schema object',
     ).toEqual([])
   })
 
-  it('publishes ./payments-contract as a second subpath that a bare node process can load', async () => {
+  it('publishes ./payments-contract as a second subpath carrying the eighteen contract values, loadable by a bare node process', async () => {
     const manifest = await readPaymentsPackageManifest()
     expect(manifest.packageName).toBe('@hearthkit/payments')
     expect(Object.keys(manifest.exportsMap).toSorted()).toEqual(['.', './payments-contract'])
     expect(JSON.stringify(manifest.exportsMap['./payments-contract'])).toContain(
-      './src/payments-contract.ts',
+      './src/payments-contract-entry.ts',
+    )
+
+    const subpathNamespace = await importHearthkitPaymentsContractSubpathNamespace()
+    const contractModule = paymentsContract as unknown as Record<string, unknown>
+    const subpathValueExportNames = Object.keys(subpathNamespace)
+      .filter((exportName) => subpathNamespace[exportName] !== undefined)
+      .toSorted()
+    expect(
+      subpathValueExportNames,
+      'src/payments-contract-entry.ts must export exactly the eighteen allowlisted names that live in payments-contract.ts',
+    ).toEqual([...hearthkitPaymentsContractSubpathValueExportNames].toSorted())
+
+    const rebuiltInsteadOfReExported = hearthkitPaymentsContractSubpathValueExportNames.filter(
+      (exportName) => subpathNamespace[exportName] !== contractModule[exportName],
     )
+    expect(
+      rebuiltInsteadOfReExported,
+      'these must be the identical value payments-contract.ts exports, not a second copy of it',
+    ).toEqual([])
 
     // The reason the subpath exists: the `.` entry imports the Stripe SDK, drizzle-orm/pg-core and
-    // the table definitions, while this file imports zod at runtime and nothing else — its stripe,
-    // drizzle-orm/node-postgres and @hearthkit/auth/auth-contract imports are type-only and erased.
-    const bareNodeRun = await runPaymentsContractUnderBareNode()
-    expect(bareNodeRun.exitCode, bareNodeRun.standardError).toBe(0)
+    // the table definitions, while both of these files import zod at runtime and nothing else. Each
+    // is run on its own so a failure names the file, and stderr must be empty as well as the exit
+    // code zero, because a module that warns on load still breaks a bare consumer.
+    for (const bareNodeRun of await runPaymentsContractModulesUnderBareNode()) {
+      expect(bareNodeRun.exitCode, `${bareNodeRun.modulePath}: ${bareNodeRun.standardError}`).toBe(
+        0,
+      )
+      expect(bareNodeRun.standardError, `${bareNodeRun.modulePath} wrote to stderr`).toBe('')
+    }
   })
 })