@havenpay/core

Shared TypeScript contracts for Havenpay SDKs.

@havenpay/core is the dependency every Havenpay SDK builds on. It contains the payment state machine, public domain types, provider and currency identifiers, webhook event names, generated API contract metadata, validation helpers, and typed error primitives used across browser, React Native, and server packages.

It does not make network requests. It does not read environment variables. It does not contain server credentials, provider adapters, webhook signing helpers, database code, or UI components.

Install

bun add @havenpay/core

npm install @havenpay/core

Use it for

• Building typed payment status displays.
• Sharing Havenpay public contracts between app, backend, and tests.
• Validating state transitions before rendering or persisting payment state.
• Importing generated current API operation metadata for SDK tooling.
• Keeping client and server packages aligned without duplicating domain types.

Quickstart

import type { PaymentIntentStatus } from '@havenpay/core'
import {
  isTerminalPaymentIntentStatus,
  paymentIntentTransition,
  shouldReconcilePaymentIntentStatus,
} from '@havenpay/core'

const current: PaymentIntentStatus = 'processing'
const next: PaymentIntentStatus = 'unknown'

const transition = paymentIntentTransition(current, next)

if (transition.isErr()) {
  throw new Error(transition.error.message)
}

if (isTerminalPaymentIntentStatus(transition.value)) {
  console.info('The payment no longer needs polling.')
}

if (shouldReconcilePaymentIntentStatus(transition.value)) {
  console.info('Ask the server to reconcile provider state.')
}

Main exports

| Export | Purpose | | --- | --- | | PaymentIntentStatus | Public payment lifecycle status union. | | NextAction | Provider-neutral customer action model for OTP, phone authorization, QR, and provider polling flows. | | Currency | Supported public currency identifiers. | | ProviderId | Provider identifier union used by public SDK contracts. | | WebhookEventType | Event names emitted to merchant webhook endpoints. | | paymentIntentTransition | Typed transition validator returning a neverthrow result. | | isTerminalPaymentIntentStatus | Terminal-state helper for UI and polling loops. | | shouldReconcilePaymentIntentStatus | Helper for provider-uncertain states that need server reconciliation. |

Entrypoints

import { paymentIntentTransition } from '@havenpay/core'
import { apiOperations, apiVersion } from '@havenpay/core/api'

| Entrypoint | Contents | | --- | --- | | @havenpay/core | Public types, constants, and state helpers. | | @havenpay/core/api | Current generated API operation metadata, API version, and typed client contract for SDK and contract tooling. |

Security boundary

This package is intentionally platform-neutral. It must remain safe to import from browsers, React Native, server processes, tests, and build tools.

It must not include:

• Merchant secret API keys.
• Payment client_secret storage.
• Webhook signing secret verification.
• Provider credential handling.
• Provider adapters or live provider calls.
• Database, Redis, queue, or runtime globals.

Package boundaries

Use @havenpay/core for shared contracts only.

• Use @havenpay/server for secret-key backend operations.
• Use @havenpay/web for browser payment-sheet flows.
• Use @havenpay/web-elements for optional custom elements.
• Use @havenpay/react-native for Expo and bare React Native payment flows.

Do not redefine public Havenpay payment, provider, webhook, or project types in application code. Import them here so client and server behavior stays aligned.

Versioning

Changes to public unions, state transitions, generated API metadata, or validation behavior are SDK contract changes and should be reviewed with the dependent SDK packages before publishing.