---
title: "@playstack/delivery-history"
description: "Durable provider-neutral delivery timelines, feedback transitions, support queries, and retention."
tags: ["package","communication","delivery","history","prisma","pro"]
---

{/* package-access:start */}

> **Pro.** Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@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.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

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

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

{/* package-install:end */}

## Compose

```ts
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.

{/* package-reference:start */}

## 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](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}