@playstack/delivery-history

Durable provider-neutral delivery timelines, feedback transitions, support queries, and retention.

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@playstack/delivery-history records cross-provider dispatch timelines and normalized feedback for @playstack/delivery. It is not an audit log, suppression authority, message-body archive, or provider dispatcher.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/delivery-history@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose

import { createDeliveryHistory } from '@playstack/delivery-history'
import { prismaDeliveryHistoryPersistence } from '@playstack/delivery-history/prisma'

const history = createDeliveryHistory({
  persistence: prismaDeliveryHistoryPersistence(prisma),
  clock,
  retentionMs: 90 * 24 * 60 * 60 * 1_000,
})

events.subscribe('delivery.send.dispatched', history)
await history.recordFeedback(normalizedProviderFeedback)

Configuration and operations

Property or operation	Purpose
`persistence`	Atomically records dispatches, appends feedback, runs cursor queries, and prunes rows.
`clock`	Provides the retention cutoff.
`retentionMs`	Required positive lifetime for retained history.
`recordFeedback(feedback)`	Applies an idempotent provider event by stable provider event ID.
`query(query)`	Returns up to 100 records using cursor pagination and indexed filters.
`prune()`	Removes rows older than the configured retention window.

Bounced and complained states are terminal, opened implies delivered, and older feedback cannot move a record backward. Provider webhook normalization remains an application-edge responsibility.

@playstack/delivery-history/prisma supplies the persistence adapter and the delivery-history.prisma managed artifact. @playstack/delivery-history/testing supplies an in-memory implementation. Neither stores message bodies or raw destinations.

API entry points and requirements

Reference snapshot: @playstack/delivery-history@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Public entry point	Declaration file
`@playstack/delivery-history`	`./dist/index.d.ts`
`@playstack/delivery-history/errors`	`./dist/errors.d.ts`
`@playstack/delivery-history/prisma`	`./dist/prisma.d.ts`
`@playstack/delivery-history/testing`	`./dist/testing.d.ts`
`@playstack/delivery-history/package.json`	No TypeScript declaration (asset or metadata export).

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.