payload-abandoned-cart 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 George Vasiliades
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,217 @@
1
+ # payload-abandoned-cart
2
+
3
+ [![npm](https://img.shields.io/npm/v/payload-abandoned-cart?style=flat-square&color=0F766E)](https://www.npmjs.com/package/payload-abandoned-cart) ![node](https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square) ![license](https://img.shields.io/badge/license-MIT-6C757D?style=flat-square)
4
+
5
+ Records when a Payload cart was abandoned, sends a recovery sequence through `payload.sendEmail`, restores the cart from a link that expires, and marks the orders that came back so a shop can measure whether any of it works.
6
+
7
+ - Extends `@payloadcms/plugin-ecommerce`, adding fields and endpoints instead of replacing anything
8
+ - No scheduler dependency: one endpoint you point your own cron at, and the same work as an exported function
9
+ - No mail library: every message goes through the email adapter the host already configured
10
+ - No runtime dependencies, no admin components, so it survives minor releases
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pnpm add payload-abandoned-cart
16
+ ```
17
+
18
+ ```ts
19
+ import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
20
+ import { abandonedCartPlugin } from 'payload-abandoned-cart'
21
+
22
+ export default buildConfig({
23
+ plugins: [
24
+ ecommercePlugin({ ... }),
25
+ abandonedCartPlugin({
26
+ idleMinutes: 120,
27
+ steps: [{ delayMinutes: 60 }, { delayMinutes: 1440 }],
28
+ sweepSecret: process.env.ABANDONED_CART_SECRET,
29
+ }),
30
+ ],
31
+ })
32
+ ```
33
+
34
+ `abandonedCartPlugin` must come after `ecommercePlugin`, because it adds fields to the collections that plugin defines. Then point a scheduler at the sweep:
35
+
36
+ ```bash
37
+ curl -X POST https://example.com/api/abandoned-cart/sweep \
38
+ -H "Authorization: Bearer $ABANDONED_CART_SECRET"
39
+ ```
40
+
41
+ ## What was measured
42
+
43
+ Read in the published `@payloadcms/plugin-ecommerce@3.88.0`, in the original TypeScript carried by its source maps.
44
+
45
+ ### The abandoned status exists and is never stored
46
+
47
+ The carts collection declares three statuses in `src/collections/carts/createCartsCollection.ts`, and the field carries `virtual: true` with an `afterRead` hook. `src/collections/carts/statusBeforeRead.ts` is the whole of it:
48
+
49
+ ```
50
+ if (data?.purchasedAt) return 'purchased'
51
+ if (timeNow - createdAt < 7 * 24 * 60 * 60 * 1000) return 'active'
52
+ return 'abandoned'
53
+ ```
54
+
55
+ So the value is computed on every read and written nowhere. Four consequences, all of which this package exists to answer:
56
+
57
+ | What the plugin does | What follows |
58
+ | --- | --- |
59
+ | The field is `virtual: true` | It is not in the database. Payload's own query validation pushes an error for a query on a field with `virtual: true`, so `where: { status: { equals: 'abandoned' } }` cannot be run at all |
60
+ | The threshold is the literal `7 * 24 * 60 * 60 * 1000` | Seven days, not configurable |
61
+ | It is measured from `createdAt` | A cart created eight days ago and updated this morning already reads as abandoned |
62
+ | Nothing records when it changed | There is no moment to count a recovery sequence from |
63
+
64
+ This package therefore stores its own `abandonedAt` timestamp rather than trying to write a field that would be discarded. If your carts collection carries a stored status field of its own that offers an `abandoned` option, that field is written too; the virtual one never is.
65
+
66
+ ### A cart holds no address
67
+
68
+ The fields the plugin puts on a cart are `items`, `secret`, `customer`, `purchasedAt`, `status`, and, when currencies are configured, `subtotal` and `currency`. There is no email address anywhere, and no `shippingAddress` either; only orders have one of those.
69
+
70
+ A cart can therefore only be emailed if it has a `customer` relationship to look an address up through, which a guest cart does not. This package adds a `customerEmail` field to the cart so that a storefront can capture the address at the first step of checkout, and reads it before falling back to the customer record.
71
+
72
+ ### The order does not know which cart it came from
73
+
74
+ In `src/payments/adapters/stripe/confirmOrder.ts` the order is created first and the cart is marked second, inside one request:
75
+
76
+ ```
77
+ const order = await payload.create({ collection: ordersSlug, data: { ... }, req })
78
+ await payload.update({ id: cartID, collection: cartsSlug, data: { purchasedAt: timestamp }, req })
79
+ ```
80
+
81
+ The order carries `items`, `customer` or `customerEmail`, `transactions`, `status`, `amount` and `currency`. Nothing points back at the cart. Attribution is therefore taken from the only moment the two are known together: the order id is kept in `req.context` as the order is created, and the cart's own hook, running later in the same request, writes it onto the order.
82
+
83
+ ## Options
84
+
85
+ | Option | Default | Meaning |
86
+ | --- | --- | --- |
87
+ | `attributionWindowHours` | `168` | How long after a recovery link is followed a purchase is still credited to it |
88
+ | `cartsSlug` | `'carts'` | Slug of the carts collection |
89
+ | `currencyDecimals` | `2` | Decimal places used to format the subtotal, one number or a map from currency code to places |
90
+ | `customersSlug` | `'users'` | Collection the cart's `customer` relationship points at |
91
+ | `disabled` | `false` | Stops marking, sending and attributing but keeps every field, so the database keeps its shape |
92
+ | `emailFieldName` | `'customerEmail'` | Field on the cart holding the address a message is sent to |
93
+ | `from` | `null` | Address messages are sent from. Null leaves the choice to the email adapter |
94
+ | `idleMinutes` | `60` | Minutes of inactivity, measured on `updatedAt`, before a cart is marked abandoned |
95
+ | `markLimit` | `200` | Highest number of carts marked in one sweep |
96
+ | `ordersSlug` | `'orders'` | Slug of the orders collection |
97
+ | `recoverEndpointPath` | `'/abandoned-cart/recover'` | Path a recovery link points at |
98
+ | `redirectPath` | `'/cart'` | Storefront path a followed link is redirected to. Empty means answer with JSON instead |
99
+ | `redirectWithSecret` | `true` | Whether the redirect carries the cart secret, which is what gives a guest the cart back |
100
+ | `replyTo` | `null` | Address replies go to |
101
+ | `sendLimit` | `100` | Highest number of messages sent in one sweep |
102
+ | `serverURL` | `''` | Origin used to build recovery links. Empty falls back to `serverURL` of the Payload config |
103
+ | `statusFieldName` | `'status'` | Cart status field. Written only when it is stored and offers an `abandoned` option |
104
+ | `steps` | two messages, at 60 and 1440 minutes | The sequence. An empty array turns sending off and leaves marking in place |
105
+ | `sweepEndpointPath` | `'/abandoned-cart/sweep'` | Path of the sweep endpoint |
106
+ | `sweepSecret` | `''` | Secret accepted by that endpoint as `Authorization: Bearer <secret>`. Empty means only a signed in user may call it |
107
+ | `tokenTtlHours` | `336` | How long a recovery token stays valid, counted from the moment the cart was marked |
108
+
109
+ A value that cannot be used is replaced by its default rather than being applied. An `idleMinutes` of `0` becomes `60`, `90.9` becomes `90`, a slug given as an empty string becomes its default, and a path without a leading slash gains one. Steps are sorted by delay, so the sequence always goes out in the order the delays describe.
110
+
111
+ ### The sequence
112
+
113
+ Each step's `delayMinutes` is counted from `abandonedAt`, not from the message before it, so the schedule stays readable as steps are added or removed.
114
+
115
+ ```ts
116
+ abandonedCartPlugin({
117
+ steps: [
118
+ { delayMinutes: 60 },
119
+ {
120
+ delayMinutes: 1440,
121
+ template: {
122
+ subject: 'Still thinking it over?',
123
+ text: 'Your basket of {{itemCount}} items comes to {{subtotalFormatted}}.\n{{recoveryURL}}',
124
+ },
125
+ },
126
+ { delayMinutes: 4320, template: (context) => ({ subject: '...', text: '...' }) },
127
+ ],
128
+ })
129
+ ```
130
+
131
+ A template is either a pair of strings carrying `{{placeholder}}` tokens or a function receiving the context. The tokens are `abandonedAt`, `cartID`, `currency`, `itemCount`, `lineCount`, `recoveryURL`, `step`, `subtotal`, `subtotalFormatted` and `to`; the whole cart is on `cart` for a function template. A token with no matching value is left in place, so a mistyped name is visible instead of blank. The built in messages are plain text and compose nothing into markup.
132
+
133
+ ## What it adds to your database
134
+
135
+ | Collection | Field | Type | Notes |
136
+ | --- | --- | --- | --- |
137
+ | your carts collection | `customerEmail` | email | indexed. Added only when no field of that name exists |
138
+ | your carts collection | `abandonedAt` | date | indexed. Set by the sweep, cleared when the link is followed |
139
+ | your carts collection | `recoveryToken` | text | indexed, hidden, closed to create, read and update through the API |
140
+ | your carts collection | `recoveryTokenExpiresAt` | date | hidden |
141
+ | your carts collection | `recoveryEmailsSent` | number | how many steps have gone out, read only |
142
+ | your carts collection | `lastRecoveryEmailAt` | date | read only |
143
+ | your carts collection | `recoveryVisitedAt` | date | indexed. When the recovery link was first followed |
144
+ | your orders collection | `recoveredFromCart` | relationship | indexed, read only. The cart the sale came back from |
145
+ | your orders collection | `recoveryEmailStep` | number | read only. How many messages had gone out when the sale happened |
146
+
147
+ No collection is added. A field this package would add and your collection already declares under that name is left alone.
148
+
149
+ ## What it adds to your API
150
+
151
+ | Endpoint | Method | Purpose |
152
+ | --- | --- | --- |
153
+ | `/api/abandoned-cart/recover?token=...` | get | Public. Restores the cart and redirects to the storefront |
154
+ | `/api/abandoned-cart/sweep` | post | Marks idle carts and sends what is due. Returns `{ "marked": n, "sent": n, "skipped": n }` |
155
+
156
+ ### Running the sweep
157
+
158
+ There are three ways, none of which needs a scheduler in your dependencies:
159
+
160
+ 1. Point your existing scheduler at the endpoint, with the secret as a bearer token.
161
+ 2. Call it from a route handler or a script.
162
+
163
+ ```ts
164
+ import { runAbandonedCartSweep } from 'payload-abandoned-cart'
165
+
166
+ const { marked, sent, skipped } = await runAbandonedCartSweep(payload, { idleMinutes: 120 })
167
+ ```
168
+
169
+ 3. Call the two halves separately, when marking and sending belong on different schedules.
170
+
171
+ ```ts
172
+ import { markAbandonedCarts, sendRecoveryEmails } from 'payload-abandoned-cart'
173
+ ```
174
+
175
+ Pass the same options you passed to the plugin. Every exported function resolves them the same way the plugin does, so passing nothing gives you the documented defaults.
176
+
177
+ ### The recovery link
178
+
179
+ A token is 32 bytes from `getRandomValues` of `node:crypto`, written as 64 hexadecimal characters, minted when the cart is marked and reused by every message of the sequence so that an older message keeps working. Following the link stops the cart being abandoned, which also stops the sequence, records the visit, and redirects to:
180
+
181
+ ```
182
+ /cart?cart=<id>&secret=<cart secret>
183
+ ```
184
+
185
+ The secret is what the ecommerce plugin's own guest cart access reads from `req.query.secret`, so a guest gets the cart back rather than an empty one. Set `redirectWithSecret: false` to leave it out, or `redirectPath: ''` to receive JSON and do the rest yourself:
186
+
187
+ ```json
188
+ { "cart": "68f2...", "recovered": true, "secret": "3f9a..." }
189
+ ```
190
+
191
+ A refused link answers `404` for a token that belongs to nothing, `410` for one that expired and `409` for a cart already paid for. With a redirect configured, all three become `?recovery=unknown`, `?recovery=expired` and `?recovery=purchased` on the storefront path instead.
192
+
193
+ ## Honest limits
194
+
195
+ **One sweep at a time.** The sweep is not locked. Two overlapping runs can read the same cart before either has written to it, and send one step twice. Space your schedule wider than a sweep takes, and keep `markLimit` and `sendLimit` at a size that finishes comfortably.
196
+
197
+ **A message is recorded before it is sent.** The step counter is written first and the transport called second, so a cart is never sent the same step twice. The cost is the opposite failure: if the transport throws, that message is lost rather than repeated. The failure is logged as an error and the sweep continues to the next cart. Losing one message is better than mailing a customer twice.
198
+
199
+ **The sweep does not run inside your request transaction.** Each cart is written on its own, so a failure late in a sweep does not roll back the messages already sent. On PostgreSQL that means the sweep uses a connection of its own while the endpoint holds another; the same mechanism was measured for `payload-order-numbers`, where the `pg` default pool of 10 was exhausted by fifteen simultaneous writers. One scheduled sweep is one extra connection, but do not run the sweep from inside a hot request path.
200
+
201
+ **A guest cart with no address is never mailed.** The ecommerce plugin gives a cart no address field, so unless your storefront writes one into `customerEmail`, only carts with a `customer` relationship can be reached. Those carts are still marked, still counted, and are passed over with a warning in the log rather than an error.
202
+
203
+ **The recovery token is stored as it is sent.** The same link has to appear in every message of the sequence, so the token cannot be replaced by a hash of itself. The field is closed to create, read and update through the API and hidden in the admin panel, but it is in the database in plain text. It grants access to one cart and it expires.
204
+
205
+ **The secret travels in a URL.** With `redirectWithSecret` on, the cart secret arrives on the storefront as a query parameter, which browsers keep in history and may pass on as a referrer. That is how the ecommerce plugin's own guest access works, and it is the only way to hand a guest their cart back. Turn it off if that trade is not one you want.
206
+
207
+ **Attribution needs the order and the cart in one request.** The order id is taken from `req.context`, which is how the two are connected when the official `confirmOrder` runs. A checkout that creates the order in a separate request, or writes it straight through the local API, leaves `recoveredFromCart` empty; the visit is still on the cart, and a note is written to the log.
208
+
209
+ **Nothing is measured against a control group.** `recoveredFromCart` counts sales that followed a recovery link inside the attribution window. It does not tell you whether those customers would have come back anyway.
210
+
211
+ **Existing carts are not marked retroactively.** The first sweep marks every cart already older than `idleMinutes`, up to `markLimit`, oldest first. On a shop with a long history that is several sweeps' worth of work, and the messages that follow are real. Set `steps: []` for the first run if you want the marking without the mail.
212
+
213
+ **Deleting a cart deletes its attribution.** `recoveredFromCart` is a relationship; the order keeps `recoveryEmailStep`, but the link goes.
214
+
215
+ ## License
216
+
217
+ MIT. Copyright George Vasiliades, https://github.com/Poseidonas
@@ -0,0 +1,274 @@
1
+ import { Payload, PayloadRequest, Config } from 'payload';
2
+
3
+ /**
4
+ * Values available to a recovery template, all derived from the cart being
5
+ * recovered. A value the cart does not carry is null and renders as an empty
6
+ * string.
7
+ */
8
+ type RecoveryContext = {
9
+ /** ISO timestamp the cart was marked abandoned. */
10
+ abandonedAt: string;
11
+ /** The whole cart document, for templates that need a field this context does not carry. */
12
+ cart: Record<string, unknown>;
13
+ /** Cart document id. */
14
+ cartID: string;
15
+ /** Uppercase currency code held by the cart, or an empty string. */
16
+ currency: string;
17
+ /** Sum of the quantities of every line in the cart. */
18
+ itemCount: number;
19
+ /** Number of lines in the cart. */
20
+ lineCount: number;
21
+ /** Absolute recovery link, valid until the token expires. */
22
+ recoveryURL: string;
23
+ /** Which message of the sequence this is, counting from 1. */
24
+ step: number;
25
+ /** Cart subtotal in the minor unit of the currency, as stored by the ecommerce plugin. */
26
+ subtotal: null | number;
27
+ /** Cart subtotal as a decimal string followed by the currency code, such as `25.00 EUR`. */
28
+ subtotalFormatted: string;
29
+ /** Address this message is sent to. */
30
+ to: string;
31
+ };
32
+ /**
33
+ * Subject and body of one message. `html` is sent only when a template supplies it.
34
+ */
35
+ type RecoveryBody = {
36
+ html?: string;
37
+ subject: string;
38
+ text: string;
39
+ };
40
+ /**
41
+ * A message of the sequence, either a pair of strings carrying `{{placeholder}}`
42
+ * tokens or a function that receives the context and returns the body.
43
+ */
44
+ type RecoveryTemplate = ((context: RecoveryContext) => Promise<RecoveryBody> | RecoveryBody) | RecoveryBody;
45
+ /**
46
+ * One message of the recovery sequence.
47
+ */
48
+ type RecoveryStep = {
49
+ /**
50
+ * Minutes after the cart was marked abandoned before this message is due.
51
+ * Measured from `abandonedAt`, not from the previous message.
52
+ */
53
+ delayMinutes?: number;
54
+ /** Template rendered for this message. Defaults to the built in one for its position. */
55
+ template?: RecoveryTemplate;
56
+ };
57
+ /**
58
+ * One message ready to hand to `payload.sendEmail`.
59
+ */
60
+ type RecoveryMessage = {
61
+ from?: string;
62
+ html?: string;
63
+ replyTo?: string;
64
+ subject: string;
65
+ text: string;
66
+ to: string;
67
+ };
68
+ /**
69
+ * A cart as this package reads it. Every field is optional because the package
70
+ * never assumes a shape the ecommerce plugin does not guarantee.
71
+ */
72
+ type CartDocument = {
73
+ [key: string]: unknown;
74
+ customer?: unknown;
75
+ id: number | string;
76
+ items?: unknown;
77
+ purchasedAt?: unknown;
78
+ updatedAt?: unknown;
79
+ };
80
+ /**
81
+ * What one sweep did, returned by the endpoint and by the exported functions.
82
+ */
83
+ type SweepResult = {
84
+ /** Carts marked abandoned in this run. */
85
+ marked: number;
86
+ /** Recovery messages handed to `payload.sendEmail` without throwing. */
87
+ sent: number;
88
+ /** Carts whose message could not be built or sent. Logged, never thrown. */
89
+ skipped: number;
90
+ };
91
+ /**
92
+ * Why a recovery link was refused.
93
+ */
94
+ type RecoveryRefusal = 'expired' | 'purchased' | 'unknown';
95
+ /**
96
+ * Outcome of following a recovery link.
97
+ */
98
+ type RecoveryOutcome = {
99
+ cart: CartDocument;
100
+ recovered: true;
101
+ secret: null | string;
102
+ } | {
103
+ reason: RecoveryRefusal;
104
+ recovered: false;
105
+ };
106
+ type AbandonedCartConfig = {
107
+ /**
108
+ * How long after a recovery link is followed a purchase is still credited to it.
109
+ * Defaults to 168 hours, seven days.
110
+ */
111
+ attributionWindowHours?: number;
112
+ /**
113
+ * Slug of the carts collection. Defaults to 'carts'.
114
+ */
115
+ cartsSlug?: string;
116
+ /**
117
+ * Decimal places used when formatting the subtotal, either one number for every
118
+ * currency or a map from currency code to places. Defaults to 2.
119
+ */
120
+ currencyDecimals?: number | Record<string, number>;
121
+ /**
122
+ * Slug of the customers collection the cart's `customer` relationship points at.
123
+ * Defaults to 'users'.
124
+ */
125
+ customersSlug?: string;
126
+ /**
127
+ * Stops marking, sending and attributing while leaving every field in place,
128
+ * so that an existing database keeps its shape.
129
+ */
130
+ disabled?: boolean;
131
+ /**
132
+ * Field on the cart holding the address a recovery message is sent to.
133
+ * Defaults to 'customerEmail'. The plugin adds the field when the carts
134
+ * collection does not already have one under this name.
135
+ */
136
+ emailFieldName?: string;
137
+ /**
138
+ * Address recovery messages are sent from. Defaults to null, which leaves the
139
+ * choice to the email adapter.
140
+ */
141
+ from?: null | string;
142
+ /**
143
+ * Minutes of inactivity, measured on the cart's `updatedAt`, before a cart is
144
+ * marked abandoned. Defaults to 60.
145
+ */
146
+ idleMinutes?: number;
147
+ /**
148
+ * Highest number of carts marked abandoned in one sweep. Defaults to 200.
149
+ */
150
+ markLimit?: number;
151
+ /**
152
+ * Slug of the orders collection recovered orders are attributed on.
153
+ * Defaults to 'orders'.
154
+ */
155
+ ordersSlug?: string;
156
+ /**
157
+ * Path of the endpoint a recovery link points at.
158
+ * Defaults to '/abandoned-cart/recover'.
159
+ */
160
+ recoverEndpointPath?: string;
161
+ /**
162
+ * Storefront path a followed recovery link is redirected to, with the cart id
163
+ * appended as a query parameter. Defaults to '/cart'.
164
+ */
165
+ redirectPath?: string;
166
+ /**
167
+ * Whether the redirect carries the cart secret, which is what lets a guest
168
+ * regain a cart the ecommerce plugin protects with that secret.
169
+ * Defaults to true.
170
+ */
171
+ redirectWithSecret?: boolean;
172
+ /**
173
+ * Address replies to recovery messages go to. Defaults to null.
174
+ */
175
+ replyTo?: null | string;
176
+ /**
177
+ * Highest number of recovery messages sent in one sweep. Defaults to 100.
178
+ */
179
+ sendLimit?: number;
180
+ /**
181
+ * Field on the cart holding its status. The status field the ecommerce plugin
182
+ * defines is virtual, so it is never written; a stored field of this name that
183
+ * offers an `abandoned` option is written alongside `abandonedAt`.
184
+ * Defaults to 'status'.
185
+ */
186
+ statusFieldName?: string;
187
+ /**
188
+ * Absolute origin used to build recovery links. Defaults to an empty string,
189
+ * which falls back to `serverURL` of the Payload config.
190
+ */
191
+ serverURL?: string;
192
+ /**
193
+ * The recovery sequence, one entry per message. An empty array turns sending
194
+ * off and leaves marking in place. Defaults to two messages, at one hour and
195
+ * at 24 hours after the cart was marked abandoned.
196
+ */
197
+ steps?: RecoveryStep[];
198
+ /**
199
+ * Path of the endpoint that runs a sweep. Defaults to '/abandoned-cart/sweep'.
200
+ */
201
+ sweepEndpointPath?: string;
202
+ /**
203
+ * Secret accepted by the sweep endpoint as `Authorization: Bearer <secret>`.
204
+ * Empty means only a signed in user may call it.
205
+ */
206
+ sweepSecret?: string;
207
+ /**
208
+ * How long a recovery token stays valid, in hours, counted from the moment the
209
+ * cart is marked abandoned. Defaults to 336 hours, fourteen days.
210
+ */
211
+ tokenTtlHours?: number;
212
+ };
213
+
214
+ /**
215
+ * Turns an amount held in the minor unit of a currency into `25.00 EUR`.
216
+ * Returns an empty string when there is no amount to show.
217
+ */
218
+ declare const formatAmount: (amount: null | number, currency: string, decimals?: number | Record<string, number>) => string;
219
+
220
+ /**
221
+ * Follows a recovery token. A cart that is found, unexpired and not yet
222
+ * purchased stops being abandoned, which also stops its message sequence, and
223
+ * records the moment the link was followed. The cart secret is returned so that
224
+ * a guest can be handed back a cart the ecommerce plugin protects with it.
225
+ */
226
+ declare const recoverCart: (payload: Payload, token: string, incoming?: AbandonedCartConfig, req?: PayloadRequest) => Promise<RecoveryOutcome>;
227
+
228
+ /**
229
+ * Marks every cart that has been idle for longer than `idleMinutes` and has not
230
+ * been purchased. Each cart receives the timestamp, a recovery token and its
231
+ * expiry. Returns how many carts were marked.
232
+ */
233
+ declare const markAbandonedCarts: (payload: Payload, incoming?: AbandonedCartConfig, req?: PayloadRequest) => Promise<number>;
234
+ /**
235
+ * Sends every recovery message that has come due. A message is recorded on the
236
+ * cart before it is handed to the transport, so a cart is never sent the same
237
+ * step twice. Returns how many messages went out and how many carts were passed
238
+ * over because no message could be built or sent.
239
+ */
240
+ declare const sendRecoveryEmails: (payload: Payload, incoming?: AbandonedCartConfig, req?: PayloadRequest) => Promise<{
241
+ sent: number;
242
+ skipped: number;
243
+ }>;
244
+ /**
245
+ * Marks idle carts and then sends whatever has come due. This is what the sweep
246
+ * endpoint calls, and what a scheduler outside Payload should call.
247
+ */
248
+ declare const runAbandonedCartSweep: (payload: Payload, incoming?: AbandonedCartConfig, req?: PayloadRequest) => Promise<SweepResult>;
249
+
250
+ /**
251
+ * Replaces `{{name}}` with the matching context value. A token with no matching
252
+ * value is left in place, so that a mistyped name is visible instead of blank.
253
+ */
254
+ declare const renderPlaceholders: (input: string, context: RecoveryContext) => string;
255
+ /**
256
+ * Resolves a template into a message body, running the placeholders of a string
257
+ * template or calling a function template with the context.
258
+ */
259
+ declare const renderTemplate: (template: RecoveryTemplate, context: RecoveryContext) => Promise<RecoveryBody>;
260
+ /**
261
+ * The messages used when a step supplies no template of its own. A step beyond
262
+ * the third reuses the third.
263
+ */
264
+ declare const defaultTemplates: RecoveryBody[];
265
+
266
+ /**
267
+ * A 256 bit recovery token, drawn from the platform random source and rendered
268
+ * as 64 hexadecimal characters. No dependency, nothing derived from the cart.
269
+ */
270
+ declare const createRecoveryToken: () => string;
271
+
272
+ declare const abandonedCartPlugin: (incoming?: AbandonedCartConfig) => (incomingConfig: Config) => Config;
273
+
274
+ export { type AbandonedCartConfig, type CartDocument, type RecoveryBody, type RecoveryContext, type RecoveryMessage, type RecoveryOutcome, type RecoveryRefusal, type RecoveryStep, type RecoveryTemplate, type SweepResult, abandonedCartPlugin, createRecoveryToken, defaultTemplates, formatAmount, markAbandonedCarts, recoverCart, renderPlaceholders, renderTemplate, runAbandonedCartSweep, sendRecoveryEmails };