@payhook/core

Low-level, environment-neutral Payhook API and entitlement utilities.

@payhook/core is the shared foundation used by @payhook/extension. Most browser-extension integrations should install the extension package instead of using Core directly.

Install

npm install @payhook/core

The package is native ESM.

API client

import {
  createPaymentHook,
  pullPaymentsFromHook,
  selectWinningPayment,
  paymentToEntitlement
} from '@payhook/core'

const hook = await createPaymentHook({
  apiKey: 'phk_live_xxx',
  extensionId: 'your_chrome_extension_id'
})

const { payments } = await pullPaymentsFromHook({
  apiKey: 'phk_live_xxx',
  extensionId: 'your_chrome_extension_id',
  paymentHookId: hook.id
})

const payment = selectWinningPayment(payments, ['prod_xxx'])
const entitlement = paymentToEntitlement(payment)

Publishable phk_live_… and phk_test_… keys are safe to embed in browser clients. Bind them to the expected extension ID and origins in the Payhook dashboard. The key prefix selects the Stripe environment.

Exports

API

• createPaymentHook() creates an install-scoped payment hook.
• pullPaymentsFromHook() retrieves Stripe-enriched payment state.
• createPayment() starts the configured confirmation or checkout flow.
• createManagePlanSession() creates a Stripe Customer Portal session.
• fetchAccountConfig() retrieves dashboard configuration with ETag support.
• trackEvent() sends credential-free Payhook analytics events.
• payhookHeaders() and parseJsonResponse() support custom low-level integrations.

Entitlements

• selectWinningPayment() chooses the best active payment within an explicit product scope.
• paymentToEntitlement() converts a payment into a stable access snapshot.
• isActivePayment() applies Payhook's active-status predicate.
• matchesProductId() checks product scope without matching unknown products.

Product matching fails closed until a scope is known. Pass explicit product IDs, or use the higher-level extension SDK to load the product release channel from the Payhook dashboard.

Core is deliberately cache-neutral: pullPaymentsFromHook() rejects upstream errors. The higher-level extension SDK owns the sanitized last-known-good entitlement cache and decides when startup may continue from it.

Endpoint derivation

Persist the payment hook ID, not endpoint URLs. Hook-scoped URLs are deterministic:

POST {apiUrl}/v1/payment_hooks/{paymentHookId}/pull
POST {apiUrl}/v1/payment_hooks/{paymentHookId}/manage_plan

managePlanUrl remains accepted only for compatibility with older integrations.

Documentation

• Chrome extension integration
• Payhook API
• Payhook dashboard

License

ISC