@framers/agentos-ext-channel-email 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @framers/agentos-ext-channel-email
 
-Email for AgentOS. `EmailService` sends mail through SMTP or Resend's HTTPS API, and reads, searches, extracts codes from and replies to mail through IMAP. The pack's factory wraps the service in a messaging-channel adapter and five tools for an agent.
+Email for AgentOS. `EmailService` sends mail through SMTP or Resend's HTTPS API, and reads, searches, extracts codes from and replies to mail through IMAP. The pack's factory wraps the service in a messaging-channel adapter and five tools for an agent. Two stores on a host's SQL database keep what a sender reads before a send: a suppression record and the tokens of unsubscribe links.
 
 ## Installation
 
@@ -83,6 +83,43 @@ Through Resend the fields go in the request's `headers` ([custom headers](https:
 
 `headers` adds fields and never replaces the service's own: `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Subject`, `Date`, `Message-ID`, `MIME-Version` and every `Content-` field are refused, in any case. The recipients, the reply-to and the subject have their own options, and the From comes from the configuration's `from`. A name given twice in different cases is refused too. A refusal throws an `Error` before either transport is used, naming the field, or its place in the object when its name is at fault, and none of its value. The `emailSend` tool and the channel adapter add no header fields.
 
+## Suppressions and unsubscribe tokens
+
+Two stores a sender reads, each on the host's SQL database: `SqlSuppressionStore` keeps the addresses not to mail, each named by its SHA-256, and `SqlRecipientCapability` keeps opaque tokens, such as an unsubscribe link's, each naming a recipient and a scope. Both take [`@framers/sql-storage-adapter`](https://www.npmjs.com/package/@framers/sql-storage-adapter)'s adapter on SQLite or PostgreSQL, or any handle with its `run` and `get` (`?` placeholders, positional parameters), so the pack gains no dependency.
+
+```ts
+import { createHash } from 'node:crypto';
+import { createDatabase } from '@framers/sql-storage-adapter';
+import {
+  DEFAULT_SUPPRESSION_SCOPE,
+  SqlRecipientCapability,
+  SqlSuppressionStore,
+  emailPreferencesDdl,
+} from '@framers/agentos-ext-channel-email';
+
+const db = await createDatabase({ url: process.env.DATABASE_URL });
+await db.exec(emailPreferencesDdl('mail')); // mail_suppressions and mail_capabilities
+
+// A bounce reported by the provider: the store gets the address's hash, never the address.
+const suppressions = new SqlSuppressionStore(db, 'mail');
+const addressHash = createHash('sha256').update('reader@example.com'.toLowerCase()).digest('hex');
+await suppressions.suppress(DEFAULT_SUPPRESSION_SCOPE, addressHash, 'bounce', '2026-10-15');
+const skip = await suppressions.isSuppressed(DEFAULT_SUPPRESSION_SCOPE, addressHash); // true: send nothing
+
+// An unsubscribe link: the message's id is the nonce, so a retried message carries the same token.
+const tokens = new SqlRecipientCapability(db, 'mail');
+const key = Buffer.from(process.env.UNSUBSCRIBE_KEY ?? '', 'hex'); // 32 bytes or more, kept secret
+const token = await tokens.issue('account-1', 'weekly-summary', 'message-42', key);
+const link = `https://example.com/unsubscribe?t=${token}`;
+const grant = await tokens.find(token); // { recipient: 'account-1', scope: 'weekly-summary' }, or null
+```
+
+`suppress(scope, addressHash, reason, day)` records an address in a scope with its reason and its day (`YYYY-MM-DD`), and no end. The reason is `bounce`, `complaint`, `suppressed` (the provider refused a message because its own list held the address) or `manual`. A second record of the address in the scope writes nothing and keeps the first, so a provider's repeated event is harmless; `suppress` answers `true` only for the call that recorded it, and two hosts recording one address at once leave one row. `isSuppressed(scope, addressHash)` answers for one scope. A scope is one list, and a host that keeps one passes `DEFAULT_SUPPRESSION_SCOPE` (`mail`) everywhere. `addressHash` is the SHA-256 of the address as 64 lower-case hexadecimal characters, which the host computes the same way wherever it reads or writes the record. Any other value, an address among them, throws a `TypeError` that holds none of it, so a mistake stores nothing and is never answered as not suppressed.
+
+`issue(recipient, scope, nonce, key)` answers base64url of HMAC-SHA256 over the nonce under the key, 43 characters, and stores the token's SHA-256 beside the recipient and the scope: the token carries neither, and the table holds nothing it can be recovered from. The same nonce under the same key gives the same token, so each message takes a nonce of its own, such as its id. Issuing it again for the same recipient and scope writes nothing; for another recipient or scope it throws, and the first token keeps its recipient and scope. The key is 32 bytes or more, given as bytes; a different key gives different tokens for the same nonces. `find(token)` answers the recipient and the scope, or `null` for a token that is malformed, unknown, revoked or past its expiry: it looks the token up by its SHA-256 and compares in constant time. `revoke(recipient)` ends every token of the recipient, in every scope, and answers how many it ended. Each revoked row stays, marked with the time of the revoke, so `issue` refuses a revoked token's nonce for every recipient, scope and expiry: a revoked link never works again and never comes to name someone else. A message that needs a working token after a revoke takes a new nonce, and the token it gets works. A token has no expiry unless `issue`'s options set `expiresAt`, in epoch milliseconds.
+
+`suppressionStoreDdl(prefix)` makes the table `<prefix>_suppressions`, `recipientCapabilityDdl(prefix)` makes `<prefix>_capabilities` (`token_hash`, `recipient`, `scope`, `expires_at`, `revoked_at`) with its index on the recipient, and `emailPreferencesDdl(prefix)` makes both. The prefix is a lower-case letter and at most 39 lower-case letters, digits or underscores, and it keeps two hosts on one database apart. The statements are `CREATE ... IF NOT EXISTS` and run on SQLite and PostgreSQL. A token's row refuses its nonce for as long as it stays, revoked or not. A host that deletes a recipient's rows, by its own foreign key with `ON DELETE CASCADE` or by hand, never issues their nonces again: each message's nonce is one no other message ever had, such as a random id or a row id that is never reused. A host that cannot promise that calls `revoke` with each deletion and keeps the rows. Each store checks every argument before its first statement and lets a database error through as it was thrown. A store made on the handle that the adapter's `transaction` gives its callback writes inside that transaction.
+
 ## Errors and retries
 
 A refusal from Resend throws `EmailApiError`, with `status` (the HTTP status), `type` (Resend's error name, such as `validation_error`, or `unknown` when the answer's body is not JSON, names no error, or names one that is not 1 to 64 letters, digits, `_`, `.`, `:` or `-`) and `retryAfterSeconds` (the answer's `retry-after`, or `null`). Its message names the status and the type and never carries Resend's message, which can quote an address.
@@ -121,7 +158,12 @@ The subject, the bodies and the message id a reply names must be text. Through S
 | `EmailApiError`, `retryWaitSeconds` | A refusal from Resend, and the wait before its retry (`null` for none) |
 | `EmailChannelAdapter` | The messaging-channel adapter |
 | `EmailSendTool`, `EmailReadTool`, `EmailSearchTool`, `EmailExtractCodesTool`, `EmailReplyTool` | The five tools |
+| `SqlSuppressionStore`, `suppressionStoreDdl(prefix)` | The suppression record on a SQL database, and its table's DDL |
+| `SqlRecipientCapability`, `recipientCapabilityDdl(prefix)` | Recipient capabilities on a SQL database, and their table's DDL |
+| `emailPreferencesDdl(prefix)` | Both tables' DDL |
+| `DEFAULT_SUPPRESSION_SCOPE`, `SUPPRESSION_REASONS` | The scope of a host that keeps one list (`mail`), and the reasons an address is suppressed |
 | `EmailConfig`, `SendEmailOptions`, `EmailMessage`, `SearchEmailOptions`, `ResendOptions`, `OutgoingEmail`, `OutgoingAttachment`, `EmailChannelOptions`, `ExtensionContext`, `ExtensionPack` | The types of the configuration, the messages, the options and the pack |
+| `SuppressionStore`, `SuppressionReason`, `RecipientCapability`, `RecipientGrant`, `RecipientCapabilityIssueOptions`, `SqlRecipientCapabilityOptions`, `EmailPreferencesDb` | The stores' interfaces, their answers and options, and what they need of a database |
 
 ## License
 

package/dist/index.d.ts

@@ -3,7 +3,9 @@
  *
  * Provides an IChannelAdapter + 5 tools for sending, reading, searching,
  * extracting codes from, and replying to emails: it sends through SMTP or
- * Resend's HTTPS API and reads through IMAP.
+ * Resend's HTTPS API and reads through IMAP. It also provides the stores a
+ * sender reads on a host's SQL database: the suppression record and
+ * recipient capabilities (`./preferences`).
  *
  * @module @framers/agentos-ext-channel-email
  */
@@ -59,4 +61,6 @@ export { EmailReadTool } from './tools/read.js';
 export { EmailSearchTool } from './tools/search.js';
 export { EmailExtractCodesTool } from './tools/extractCodes.js';
 export { EmailReplyTool } from './tools/reply.js';
+export { DEFAULT_SUPPRESSION_SCOPE, SUPPRESSION_REASONS, SqlRecipientCapability, SqlSuppressionStore, emailPreferencesDdl, recipientCapabilityDdl, suppressionStoreDdl, } from './preferences/index.js';
+export type { EmailPreferencesDb, RecipientCapability, RecipientCapabilityIssueOptions, RecipientGrant, SqlRecipientCapabilityOptions, SuppressionReason, SuppressionStore, } from './preferences/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAeH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAkFD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAgC5E;AAMD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAeH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAkFD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAgC5E;AAMD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,+BAA+B,EAC/B,cAAc,EACd,6BAA6B,EAC7B,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -5,12 +5,14 @@
  *
  * Provides an IChannelAdapter + 5 tools for sending, reading, searching,
  * extracting codes from, and replying to emails: it sends through SMTP or
- * Resend's HTTPS API and reads through IMAP.
+ * Resend's HTTPS API and reads through IMAP. It also provides the stores a
+ * sender reads on a host's SQL database: the suppression record and
+ * recipient capabilities (`./preferences`).
  *
  * @module @framers/agentos-ext-channel-email
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailReplyTool = exports.EmailExtractCodesTool = exports.EmailSearchTool = exports.EmailReadTool = exports.EmailSendTool = exports.EmailChannelAdapter = exports.retryWaitSeconds = exports.EmailApiError = exports.ResendTransport = exports.EmailService = void 0;
+exports.suppressionStoreDdl = exports.recipientCapabilityDdl = exports.emailPreferencesDdl = exports.SqlSuppressionStore = exports.SqlRecipientCapability = exports.SUPPRESSION_REASONS = exports.DEFAULT_SUPPRESSION_SCOPE = exports.EmailReplyTool = exports.EmailExtractCodesTool = exports.EmailSearchTool = exports.EmailReadTool = exports.EmailSendTool = exports.EmailChannelAdapter = exports.retryWaitSeconds = exports.EmailApiError = exports.ResendTransport = exports.EmailService = void 0;
 exports.createExtensionPack = createExtensionPack;
 const EmailService_js_1 = require("./EmailService.js");
 const EmailChannelAdapter_js_1 = require("./EmailChannelAdapter.js");
@@ -136,4 +138,12 @@ var extractCodes_js_2 = require("./tools/extractCodes.js");
 Object.defineProperty(exports, "EmailExtractCodesTool", { enumerable: true, get: function () { return extractCodes_js_2.EmailExtractCodesTool; } });
 var reply_js_2 = require("./tools/reply.js");
 Object.defineProperty(exports, "EmailReplyTool", { enumerable: true, get: function () { return reply_js_2.EmailReplyTool; } });
+var index_js_1 = require("./preferences/index.js");
+Object.defineProperty(exports, "DEFAULT_SUPPRESSION_SCOPE", { enumerable: true, get: function () { return index_js_1.DEFAULT_SUPPRESSION_SCOPE; } });
+Object.defineProperty(exports, "SUPPRESSION_REASONS", { enumerable: true, get: function () { return index_js_1.SUPPRESSION_REASONS; } });
+Object.defineProperty(exports, "SqlRecipientCapability", { enumerable: true, get: function () { return index_js_1.SqlRecipientCapability; } });
+Object.defineProperty(exports, "SqlSuppressionStore", { enumerable: true, get: function () { return index_js_1.SqlSuppressionStore; } });
+Object.defineProperty(exports, "emailPreferencesDdl", { enumerable: true, get: function () { return index_js_1.emailPreferencesDdl; } });
+Object.defineProperty(exports, "recipientCapabilityDdl", { enumerable: true, get: function () { return index_js_1.recipientCapabilityDdl; } });
+Object.defineProperty(exports, "suppressionStoreDdl", { enumerable: true, get: function () { return index_js_1.suppressionStoreDdl; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,cAAc;AACd;;;;;;;;GAQG;;;AA0IH,kDAgCC;AAxKD,uDAAiD;AAEjD,qEAA+D;AAC/D,6CAAgD;AAChD,6CAAgD;AAChD,iDAAoD;AACpD,6DAAgE;AAChE,+CAAkD;AAgClD,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,SAAS,aAAa,CAAC,IAAyB,EAAE,OAA+B;IAC/E,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ;QACb,OAAO,CAAC,gBAAgB,CAAC;QACzB,OAAO,CAAC,iBAAiB,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,SAAS;QACrB,OAAO,CAAC,GAAG,CAAC,eAAe;QAC3B,EAAE,CAAC;IACL,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ;QACb,OAAO,CAAC,gBAAgB,CAAC;QACzB,OAAO,CAAC,iBAAiB,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,SAAS;QACrB,OAAO,CAAC,GAAG,CAAC,eAAe;QAC3B,EAAE,CAAC;IACL,MAAM,YAAY,GAChB,IAAI,CAAC,YAAY;QACjB,OAAO,CAAC,oBAAoB,CAAC;QAC7B,OAAO,CAAC,qBAAqB,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,aAAa;QACzB,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAC/B,EAAE,CAAC;IACL,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACtG,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IAEjD,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ;QACb,OAAO,CAAC,gBAAgB,CAAC;QACzB,OAAO,CAAC,iBAAiB,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,SAAS;QACrB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC9B,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ;QACb,OAAO,CAAC,gBAAgB,CAAC;QACzB,OAAO,CAAC,iBAAiB,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,SAAS;QACrB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC9B,MAAM,YAAY,GAChB,IAAI,CAAC,YAAY;QACjB,OAAO,CAAC,oBAAoB,CAAC;QAC7B,OAAO,CAAC,qBAAqB,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,aAAa;QACzB,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAElC,6GAA6G;IAC7G,MAAM,MAAM,GACV,QAAQ,KAAK,EAAE,IAAI,YAAY;QAC7B,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE;QACzE,CAAC,CAAC;YACE,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,YAAY;gBACtB,IAAI,EAAE,IAAI,CAAC,QAAQ;gBACnB,MAAM,EAAE,IAAI,CAAC,UAAU;aACxB;YACD,IAAI;SACL,CAAC;IAER,IAAI,QAAQ,IAAI,QAAQ,IAAI,YAAY,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,GAAG;YACZ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,YAAY;YACtB,IAAI,EAAE,IAAI,CAAC,QAAQ;YACnB,MAAM,EAAE,IAAI,CAAC,UAAU;SACxB,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAmBD,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAgB,mBAAmB,CAAC,OAAyB;IAC3D,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAwB,CAAC;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,IAAI,8BAAY,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,4CAAmB,CAAC,OAAO,CAAC,CAAC;IAEjD,MAAM,QAAQ,GAAG,IAAI,uBAAa,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,uBAAa,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,IAAI,2BAAe,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,gBAAgB,GAAG,IAAI,uCAAqB,CAAC,OAAO,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,IAAI,yBAAc,CAAC,OAAO,CAAC,CAAC;IAE9C,OAAO;QACL,IAAI,EAAE,oCAAoC;QAC1C,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE;YACX,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;YAClE,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;YAClE,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE;YACtE,EAAE,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE;YAClF,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE;YACpE,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;SAClF;QACD,UAAU,EAAE,KAAK,IAAI,EAAE;YACrB,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;QACtG,CAAC;QACD,YAAY,EAAE,KAAK,IAAI,EAAE;YACvB,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AAErB,2DAAwF;AAA/E,qHAAA,eAAe,OAAA;AAAE,mHAAA,aAAa,OAAA;AAAE,sHAAA,gBAAgB,OAAA;AAEzD,mEAA+D;AAAtD,6HAAA,mBAAmB,OAAA;AAC5B,2CAAgD;AAAvC,wGAAA,aAAa,OAAA;AACtB,2CAAgD;AAAvC,wGAAA,aAAa,OAAA;AACtB,+CAAoD;AAA3C,4GAAA,eAAe,OAAA;AACxB,2DAAgE;AAAvD,wHAAA,qBAAqB,OAAA;AAC9B,6CAAkD;AAAzC,0GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/preferences/RecipientCapability.d.ts

@@ -0,0 +1,100 @@
+import type { EmailPreferencesDb } from './database.js';
+/** What a token names: the recipient it was issued for and the scope it acts on. */
+export interface RecipientGrant {
+    /** The recipient, such as an account id. */
+    readonly recipient: string;
+    /** The scope, such as one kind of mail. */
+    readonly scope: string;
+}
+/** The options of one `issue`. */
+export interface RecipientCapabilityIssueOptions {
+    /** When the token stops working, in epoch milliseconds. A token issued without it works until it is revoked. */
+    readonly expiresAt?: number;
+}
+/** The options of a `SqlRecipientCapability`. */
+export interface SqlRecipientCapabilityOptions {
+    /** The clock `find` reads an expiry against and `revoke` records, in epoch milliseconds: `Date.now` unless given. */
+    readonly now?: () => number;
+}
+/**
+ * Opaque tokens that each name a recipient and a scope, kept as their SHA-256 alone. A token carries neither: only
+ * `find` maps it to them, and the store holds nothing a token can be recovered from.
+ */
+export interface RecipientCapability {
+    /**
+     * Issues the token for a nonce, such as a message's id: base64url of HMAC-SHA256 over the nonce under the key, 43
+     * characters. Issuing again with the same nonce and key, for the same recipient, scope and expiry, answers the same
+     * token and writes nothing; for another recipient, scope or expiry it throws, and the first token keeps its recipient
+     * and scope. A nonce whose token was revoked throws for every recipient, scope and expiry, so a message that needs a
+     * working token after `revoke` takes a new nonce.
+     *
+     * @param recipient The recipient, 1 to 512 characters.
+     * @param scope The scope, 1 to 512 characters.
+     * @param nonce The nonce, 1 to 512 characters: one message, one nonce, never another message's.
+     * @param key The key, 32 bytes or more, kept secret by the caller.
+     * @param options The token's expiry, if it has one.
+     * @returns The token.
+     */
+    issue(recipient: string, scope: string, nonce: string, key: Uint8Array, options?: RecipientCapabilityIssueOptions): Promise<string>;
+    /**
+     * The recipient and the scope the token was issued for, or `null` for a token that is malformed, unknown, revoked or
+     * past its expiry. The token is found by its SHA-256 and compared in constant time; a malformed token reaches no
+     * database.
+     *
+     * @param token The token as the link carried it.
+     */
+    find(token: string): Promise<RecipientGrant | null>;
+    /**
+     * Ends every token issued for the recipient, in every scope. Each token's row stays, marked revoked, so its nonce is
+     * never issued again; a token issued afterwards from a new nonce works.
+     *
+     * @param recipient The recipient, 1 to 512 characters.
+     * @returns How many tokens it ended: a token ended by an earlier revoke is not counted again.
+     */
+    revoke(recipient: string): Promise<number>;
+}
+/**
+ * The token for a nonce under a key: base64url of HMAC-SHA256, 43 characters.
+ *
+ * @param nonce The nonce, as UTF-8.
+ * @param key The key's bytes.
+ */
+export declare function capabilityToken(nonce: string, key: Uint8Array): string;
+/**
+ * What the store keeps of a token: its SHA-256 in lower-case hexadecimal.
+ *
+ * @param token The token, as UTF-8.
+ */
+export declare function capabilityTokenHash(token: string): string;
+/**
+ * The recipient capabilities' table, `<prefix>_capabilities`, and the index `revoke` reads, for a host's migration: one
+ * row a token, its SHA-256 the key, with the recipient, the scope, an optional expiry and the time the token was
+ * revoked, if it was. Both statements are `IF NOT EXISTS`, so they can run at each start, and they run on SQLite and on
+ * PostgreSQL. A row refuses its nonce for as long as it stays: a host that deletes rows, by its own foreign key with
+ * `ON DELETE CASCADE` or by hand, never issues their nonces again, and a host that cannot promise that calls `revoke`
+ * with each deletion and keeps the rows.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+export declare function recipientCapabilityDdl(prefix: string): string;
+/**
+ * Recipient capabilities on a host's SQL database, in the table `recipientCapabilityDdl` makes under the same prefix.
+ * Each argument is checked before any statement, and an error from the database reaches the caller as it was thrown.
+ */
+export declare class SqlRecipientCapability implements RecipientCapability {
+    private readonly db;
+    private readonly table;
+    private readonly now;
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @param options The clock that expiries are read against and revokes record.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db: EmailPreferencesDb, prefix: string, options?: SqlRecipientCapabilityOptions);
+    issue(recipient: string, scope: string, nonce: string, key: Uint8Array, options?: RecipientCapabilityIssueOptions): Promise<string>;
+    find(token: string): Promise<RecipientGrant | null>;
+    revoke(recipient: string): Promise<number>;
+}
+//# sourceMappingURL=RecipientCapability.d.ts.map

package/dist/preferences/RecipientCapability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecipientCapability.d.ts","sourceRoot":"","sources":["../../src/preferences/RecipientCapability.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,+BAA+B;IAC9C,gHAAgH;IAChH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,iDAAiD;AACjD,MAAM,WAAW,6BAA6B;IAC5C,qHAAqH;IACrH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;OAaG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEpD;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5C;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD;AAuDD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAY7D;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAW9D,OAAO,CAAC,QAAQ,CAAC,EAAE;IAVrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;;OAKG;gBAEgB,EAAE,EAAE,kBAAkB,EACvC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,6BAAkC;IAMvC,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,EACf,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,MAAM,CAAC;IA4BZ,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAgBnD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CASjD"}

package/dist/preferences/RecipientCapability.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlRecipientCapability = void 0;
+exports.capabilityToken = capabilityToken;
+exports.capabilityTokenHash = capabilityTokenHash;
+exports.recipientCapabilityDdl = recipientCapabilityDdl;
+/**
+ * @fileoverview Recipient capabilities: opaque tokens that each name one recipient and one scope, such as the link in a
+ * message that lets its reader stop one kind of mail without signing in. A token is base64url of HMAC-SHA256 over the
+ * caller's nonce under the caller's key, so a message retried with the same nonce carries the same token, and only the
+ * token's SHA-256 is stored, beside the recipient and the scope. A token works until its recipient's tokens are
+ * revoked, or until the expiry its issuer set. A revoked token's row stays, marked revoked, so its nonce is never issued
+ * again: a revoked link never works again, and never comes to name another recipient or scope.
+ */
+const node_crypto_1 = require("node:crypto");
+const database_js_1 = require("./database.js");
+/** A token: 43 base64url characters, 32 bytes without padding. */
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+/** The shortest key `issue` takes, HMAC-SHA256's output length; RFC 2104 section 3 discourages shorter keys. */
+const KEY_BYTES = 32;
+/**
+ * The token for a nonce under a key: base64url of HMAC-SHA256, 43 characters.
+ *
+ * @param nonce The nonce, as UTF-8.
+ * @param key The key's bytes.
+ */
+function capabilityToken(nonce, key) {
+    return (0, node_crypto_1.createHmac)('sha256', key).update(nonce, 'utf8').digest('base64url');
+}
+/**
+ * What the store keeps of a token: its SHA-256 in lower-case hexadecimal.
+ *
+ * @param token The token, as UTF-8.
+ */
+function capabilityTokenHash(token) {
+    return (0, node_crypto_1.createHash)('sha256').update(token, 'utf8').digest('hex');
+}
+/** Returns the key when it holds 32 bytes or more, and otherwise throws a `TypeError` that never holds the key. */
+function requireKey(key) {
+    if (key instanceof Uint8Array && key.byteLength >= KEY_BYTES)
+        return key;
+    throw new TypeError(`The key was refused: give it as ${KEY_BYTES} bytes or more, such as a Buffer`);
+}
+/** The expiry `issue`'s options set, or `null` for none; anything but a whole number of milliseconds is refused. */
+function requireExpiry(options) {
+    if (options === undefined)
+        return null;
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError('The options were refused: give them as an object or leave them out');
+    }
+    const expiresAt = options.expiresAt;
+    if (expiresAt === undefined)
+        return null;
+    if (typeof expiresAt === 'number' && Number.isSafeInteger(expiresAt))
+        return expiresAt;
+    throw new TypeError('The expiry was refused: give it as a whole number of epoch milliseconds or leave it out');
+}
+/** A stored expiry as a number, or `null` for none: PostgreSQL answers a BIGINT as text. */
+function expiryOf(value) {
+    return value === null || value === undefined ? null : Number(value);
+}
+/**
+ * The time a revoke records: the clock's reading in whole epoch milliseconds, or 0 when it answers no such number. A
+ * revoke must mark its rows whatever the clock says: SQLite stores a NaN as NULL, which would leave the tokens working.
+ */
+function revokedAtOf(reading) {
+    const at = typeof reading === 'number' ? Math.trunc(reading) : Number.NaN;
+    return Number.isSafeInteger(at) ? at : 0;
+}
+/** Whether two strings are equal, compared in time that does not depend on where they differ. */
+function equalInConstantTime(left, right) {
+    const a = Buffer.from(left, 'utf8');
+    const b = Buffer.from(right, 'utf8');
+    return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/** Whether a stored row was revoked: any value in `revoked_at`, which PostgreSQL answers as text. */
+function isRevoked(row) {
+    return row.revoked_at !== null && row.revoked_at !== undefined;
+}
+/**
+ * The recipient capabilities' table, `<prefix>_capabilities`, and the index `revoke` reads, for a host's migration: one
+ * row a token, its SHA-256 the key, with the recipient, the scope, an optional expiry and the time the token was
+ * revoked, if it was. Both statements are `IF NOT EXISTS`, so they can run at each start, and they run on SQLite and on
+ * PostgreSQL. A row refuses its nonce for as long as it stays: a host that deletes rows, by its own foreign key with
+ * `ON DELETE CASCADE` or by hand, never issues their nonces again, and a host that cannot promise that calls `revoke`
+ * with each deletion and keeps the rows.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+function recipientCapabilityDdl(prefix) {
+    const table = `${(0, database_js_1.requirePrefix)(prefix)}_capabilities`;
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        '  token_hash TEXT PRIMARY KEY,',
+        '  recipient TEXT NOT NULL,',
+        '  scope TEXT NOT NULL,',
+        '  expires_at BIGINT,',
+        '  revoked_at BIGINT',
+        ');',
+        `CREATE INDEX IF NOT EXISTS ${table}_recipient ON ${table} (recipient);`,
+    ].join('\n');
+}
+/**
+ * Recipient capabilities on a host's SQL database, in the table `recipientCapabilityDdl` makes under the same prefix.
+ * Each argument is checked before any statement, and an error from the database reaches the caller as it was thrown.
+ */
+class SqlRecipientCapability {
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @param options The clock that expiries are read against and revokes record.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db, prefix, options = {}) {
+        this.db = db;
+        this.table = `${(0, database_js_1.requirePrefix)(prefix)}_capabilities`;
+        this.now = options.now ?? Date.now;
+    }
+    async issue(recipient, scope, nonce, key, options) {
+        (0, database_js_1.requireName)('recipient', recipient);
+        (0, database_js_1.requireName)('scope', scope);
+        (0, database_js_1.requireName)('nonce', nonce);
+        const expiresAt = requireExpiry(options);
+        const token = capabilityToken(nonce, requireKey(key));
+        const tokenHash = capabilityTokenHash(token);
+        const inserted = await this.db.run(`INSERT INTO ${this.table} (token_hash, recipient, scope, expires_at) VALUES (?, ?, ?, ?) ` +
+            'ON CONFLICT (token_hash) DO NOTHING', [tokenHash, recipient, scope, expiresAt]);
+        if (inserted.changes === 1)
+            return token;
+        // The nonce was issued before, or a handle that reports no `changes` wrote it: the stored row decides.
+        const row = await this.db.get(`SELECT recipient, scope, expires_at, revoked_at FROM ${this.table} WHERE token_hash = ?`, [tokenHash]);
+        if (row === null || row === undefined) {
+            throw new Error('The token was not stored: its row was deleted while it was issued');
+        }
+        if (isRevoked(row)) {
+            throw new Error('The token was refused: its nonce was revoked under this key; give the message a new nonce');
+        }
+        if (row.recipient === recipient && row.scope === scope && expiryOf(row.expires_at) === expiresAt)
+            return token;
+        throw new Error('The token was refused: its nonce was issued under this key for another recipient, scope or expiry');
+    }
+    async find(token) {
+        if (typeof token !== 'string' || !TOKEN.test(token))
+            return null;
+        const tokenHash = capabilityTokenHash(token);
+        const row = await this.db.get(`SELECT token_hash, recipient, scope, expires_at, revoked_at FROM ${this.table} WHERE token_hash = ?`, [tokenHash]);
+        if (row === null || row === undefined || typeof row.token_hash !== 'string')
+            return null;
+        if (!equalInConstantTime(row.token_hash, tokenHash))
+            return null;
+        if (isRevoked(row))
+            return null;
+        const expiresAt = expiryOf(row.expires_at);
+        // Written so that a clock that answers NaN ends the token rather than keeping it.
+        if (expiresAt !== null && !(this.now() < expiresAt))
+            return null;
+        return { recipient: row.recipient, scope: row.scope };
+    }
+    async revoke(recipient) {
+        const name = (0, database_js_1.requireName)('recipient', recipient);
+        // The rows stay, so `issue` can refuse their nonces; only the live ones are marked and counted.
+        const result = await this.db.run(`UPDATE ${this.table} SET revoked_at = ? WHERE recipient = ? AND revoked_at IS NULL`, [revokedAtOf(this.now()), name]);
+        return result.changes ?? 0;
+    }
+}
+exports.SqlRecipientCapability = SqlRecipientCapability;
+//# sourceMappingURL=RecipientCapability.js.map

package/dist/preferences/RecipientCapability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecipientCapability.js","sourceRoot":"","sources":["../../src/preferences/RecipientCapability.ts"],"names":[],"mappings":"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"}

package/dist/preferences/SuppressionStore.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview The suppression record: the addresses a host must not mail, by scope, each named by the SHA-256 of the
+ * address that the host computes, so the record never holds an address. A host's senders read it before a send, and
+ * the handler of its provider's events writes it when a message bounces, draws a complaint or meets the provider's own
+ * suppression list. A second record of an address writes nothing, so a provider's repeated event is harmless.
+ */
+import type { EmailPreferencesDb } from './database.js';
+/** The reasons an address is suppressed, in the order the README lists them. */
+export declare const SUPPRESSION_REASONS: readonly ["bounce", "complaint", "suppressed", "manual"];
+/**
+ * Why an address is suppressed: `bounce` (a message to it bounced), `complaint` (its reader reported a message as
+ * spam), `suppressed` (the provider refused a message because the address was already on its own list) or `manual`
+ * (an operator, or the person, asked).
+ */
+export type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
+/** The scope of a host that keeps one list: every reader and writer of the record passes it. */
+export declare const DEFAULT_SUPPRESSION_SCOPE = "mail";
+/**
+ * The addresses a host must not mail, by scope. A scope is one list, such as all of a host's mail or one sending
+ * domain's, and most hosts keep one, `DEFAULT_SUPPRESSION_SCOPE`. An address is named by its hash, the SHA-256 of the
+ * address as 64 lower-case hexadecimal characters, which the host computes the same way wherever it reads or writes the
+ * record, such as over the address lower-cased. Anything else is refused with a `TypeError`, so an address passed by
+ * mistake is never stored and never answered as not suppressed.
+ */
+export interface SuppressionStore {
+    /**
+     * Whether the address is suppressed in the scope.
+     *
+     * @param scope The list, 1 to 512 characters.
+     * @param addressHash The SHA-256 of the address as 64 lower-case hexadecimal characters.
+     */
+    isSuppressed(scope: string, addressHash: string): Promise<boolean>;
+    /**
+     * Records the address as suppressed in the scope, with the reason and the day, and no end. A second record of the
+     * address in the scope writes nothing and leaves the first as it was, whatever its reason or day.
+     *
+     * @param scope The list, 1 to 512 characters.
+     * @param addressHash The SHA-256 of the address as 64 lower-case hexadecimal characters.
+     * @param reason Why the address is suppressed.
+     * @param day The calendar day of the event, `YYYY-MM-DD`.
+     * @returns `true` when this call recorded the address, `false` when the scope held it already.
+     */
+    suppress(scope: string, addressHash: string, reason: SuppressionReason, day: string): Promise<boolean>;
+}
+/**
+ * The suppression record's table, `<prefix>_suppressions`, for a host's migration: one row an address and scope, with
+ * the reason and the day, `CREATE TABLE IF NOT EXISTS` so it can run at each start. It runs on SQLite and on
+ * PostgreSQL.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+export declare function suppressionStoreDdl(prefix: string): string;
+/**
+ * The suppression record on a host's SQL database, in the table `suppressionStoreDdl` makes under the same prefix. A
+ * record is one `INSERT ... ON CONFLICT DO NOTHING`, so two hosts recording one address at once leave one row. Each
+ * argument is checked before any statement, and an error from the database reaches the caller as it was thrown: no
+ * failure is answered as `false`.
+ */
+export declare class SqlSuppressionStore implements SuppressionStore {
+    private readonly db;
+    private readonly table;
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db: EmailPreferencesDb, prefix: string);
+    isSuppressed(scope: string, addressHash: string): Promise<boolean>;
+    suppress(scope: string, addressHash: string, reason: SuppressionReason, day: string): Promise<boolean>;
+}
+//# sourceMappingURL=SuppressionStore.d.ts.map

package/dist/preferences/SuppressionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SuppressionStore.d.ts","sourceRoot":"","sources":["../../src/preferences/SuppressionStore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,0DAA2D,CAAC;AAE5F;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnE;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxG;AAwCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAW1D;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IASxD,OAAO,CAAC,QAAQ,CAAC,EAAE;IARrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;OAIG;gBAEgB,EAAE,EAAE,kBAAkB,EACvC,MAAM,EAAE,MAAM;IAKV,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAS7G"}

package/dist/preferences/SuppressionStore.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlSuppressionStore = exports.DEFAULT_SUPPRESSION_SCOPE = exports.SUPPRESSION_REASONS = void 0;
+exports.suppressionStoreDdl = suppressionStoreDdl;
+const database_js_1 = require("./database.js");
+/** The reasons an address is suppressed, in the order the README lists them. */
+exports.SUPPRESSION_REASONS = ['bounce', 'complaint', 'suppressed', 'manual'];
+/** The scope of a host that keeps one list: every reader and writer of the record passes it. */
+exports.DEFAULT_SUPPRESSION_SCOPE = 'mail';
+/** The SHA-256 of an address in lower-case hexadecimal. */
+const ADDRESS_HASH = /^[0-9a-f]{64}$/;
+/** A calendar day, `YYYY-MM-DD`. */
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Returns the hash when it is 64 lower-case hexadecimal characters, and otherwise throws a `TypeError` that never holds
+ * the value.
+ */
+function requireAddressHash(value) {
+    if (typeof value === 'string' && ADDRESS_HASH.test(value))
+        return value;
+    throw new TypeError('The address hash was refused: give the SHA-256 of the address as 64 lower-case hexadecimal characters');
+}
+/** Returns the reason when it is one of `SUPPRESSION_REASONS`, and otherwise throws a `TypeError`. */
+function requireReason(value) {
+    if (typeof value === 'string' && exports.SUPPRESSION_REASONS.includes(value)) {
+        return value;
+    }
+    throw new TypeError('The reason was refused: give bounce, complaint, suppressed or manual');
+}
+/** Returns the day when it is a calendar date written `YYYY-MM-DD`, and otherwise throws a `TypeError`. */
+function requireDay(value) {
+    if (typeof value === 'string') {
+        const parts = DAY.exec(value);
+        // A date that does not exist, such as the 30th of February, comes back from Date.UTC as another day.
+        if (parts !== null &&
+            new Date(Date.UTC(Number(parts[1]), Number(parts[2]) - 1, Number(parts[3]))).toISOString().slice(0, 10) === value) {
+            return value;
+        }
+    }
+    throw new TypeError('The day was refused: give a calendar date as YYYY-MM-DD');
+}
+/**
+ * The suppression record's table, `<prefix>_suppressions`, for a host's migration: one row an address and scope, with
+ * the reason and the day, `CREATE TABLE IF NOT EXISTS` so it can run at each start. It runs on SQLite and on
+ * PostgreSQL.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+function suppressionStoreDdl(prefix) {
+    const table = `${(0, database_js_1.requirePrefix)(prefix)}_suppressions`;
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        '  scope TEXT NOT NULL,',
+        '  address_hash TEXT NOT NULL,',
+        '  reason TEXT NOT NULL,',
+        '  suppressed_on TEXT NOT NULL,',
+        '  PRIMARY KEY (scope, address_hash)',
+        ');',
+    ].join('\n');
+}
+/**
+ * The suppression record on a host's SQL database, in the table `suppressionStoreDdl` makes under the same prefix. A
+ * record is one `INSERT ... ON CONFLICT DO NOTHING`, so two hosts recording one address at once leave one row. Each
+ * argument is checked before any statement, and an error from the database reaches the caller as it was thrown: no
+ * failure is answered as `false`.
+ */
+class SqlSuppressionStore {
+    /**
+     * @param db The database: `@framers/sql-storage-adapter`'s adapter, or any handle of `EmailPreferencesDb`'s shape.
+     * @param prefix The prefix the table was made under.
+     * @throws RangeError when the prefix does not fit.
+     */
+    constructor(db, prefix) {
+        this.db = db;
+        this.table = `${(0, database_js_1.requirePrefix)(prefix)}_suppressions`;
+    }
+    async isSuppressed(scope, addressHash) {
+        const params = [(0, database_js_1.requireName)('scope', scope), requireAddressHash(addressHash)];
+        const row = await this.db.get(`SELECT 1 AS hit FROM ${this.table} WHERE scope = ? AND address_hash = ?`, params);
+        return row !== null && row !== undefined;
+    }
+    async suppress(scope, addressHash, reason, day) {
+        const params = [(0, database_js_1.requireName)('scope', scope), requireAddressHash(addressHash), requireReason(reason), requireDay(day)];
+        const result = await this.db.run(`INSERT INTO ${this.table} (scope, address_hash, reason, suppressed_on) VALUES (?, ?, ?, ?) ` +
+            'ON CONFLICT (scope, address_hash) DO NOTHING', params);
+        return result.changes === 1;
+    }
+}
+exports.SqlSuppressionStore = SqlSuppressionStore;
+//# sourceMappingURL=SuppressionStore.js.map

package/dist/preferences/SuppressionStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SuppressionStore.js","sourceRoot":"","sources":["../../src/preferences/SuppressionStore.ts"],"names":[],"mappings":"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"}

package/dist/preferences/database.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview What the preference stores need of a database, and the checks of the table prefix and the names they
+ * take. Nothing here imports a database driver: the host passes its own handle.
+ */
+/**
+ * What `SqlSuppressionStore` and `SqlRecipientCapability` need of a database: a statement that answers the number of
+ * rows it changed, and a query that answers its first row, both with `?` placeholders and positional parameters.
+ * `@framers/sql-storage-adapter`'s `StorageAdapter` has this shape on SQLite and on PostgreSQL, and so does the handle
+ * its `transaction` gives a callback, so a store made on that handle writes inside the transaction.
+ */
+export interface EmailPreferencesDb {
+    /** Runs one statement; `changes` is the number of rows it inserted, updated or deleted. */
+    run(sql: string, params?: unknown[]): Promise<{
+        changes?: number;
+    }>;
+    /** Runs one query and answers its first row, or `null` (or `undefined`) when it has none. */
+    get<T>(sql: string, params?: unknown[]): Promise<T | null | undefined>;
+}
+/**
+ * Returns the prefix when it is a lower-case letter followed by at most 39 lower-case letters, digits or underscores,
+ * and otherwise throws a `RangeError`. The prefix is written into the SQL as it is, so nothing else passes.
+ *
+ * @param prefix The table prefix the caller gave.
+ */
+export declare function requirePrefix(prefix: unknown): string;
+/**
+ * Returns `value` when it is a string of 1 to 512 characters, and otherwise throws a `TypeError` that names `field` and
+ * never the value.
+ *
+ * @param field The argument's name, such as `scope`.
+ * @param value The value the caller gave.
+ */
+export declare function requireName(field: string, value: unknown): string;
+//# sourceMappingURL=database.d.ts.map

package/dist/preferences/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/preferences/database.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,2FAA2F;IAC3F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,6FAA6F;IAC7F,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACxE;AAKD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAKrD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAGjE"}

package/dist/preferences/database.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * @fileoverview What the preference stores need of a database, and the checks of the table prefix and the names they
+ * take. Nothing here imports a database driver: the host passes its own handle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requirePrefix = requirePrefix;
+exports.requireName = requireName;
+/** A table prefix: a lower-case letter, then at most 39 lower-case letters, digits or underscores. */
+const PREFIX = /^[a-z][a-z0-9_]{0,39}$/;
+/**
+ * Returns the prefix when it is a lower-case letter followed by at most 39 lower-case letters, digits or underscores,
+ * and otherwise throws a `RangeError`. The prefix is written into the SQL as it is, so nothing else passes.
+ *
+ * @param prefix The table prefix the caller gave.
+ */
+function requirePrefix(prefix) {
+    if (typeof prefix === 'string' && PREFIX.test(prefix))
+        return prefix;
+    throw new RangeError('The table prefix was refused: give a lower-case letter followed by at most 39 lower-case letters, digits or underscores');
+}
+/**
+ * Returns `value` when it is a string of 1 to 512 characters, and otherwise throws a `TypeError` that names `field` and
+ * never the value.
+ *
+ * @param field The argument's name, such as `scope`.
+ * @param value The value the caller gave.
+ */
+function requireName(field, value) {
+    if (typeof value === 'string' && value.length > 0 && value.length <= 512)
+        return value;
+    throw new TypeError(`The ${field} was refused: give it as a string of 1 to 512 characters`);
+}
+//# sourceMappingURL=database.js.map

package/dist/preferences/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/preferences/database.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAwBH,sCAKC;AASD,kCAGC;AA1BD,sGAAsG;AACtG,MAAM,MAAM,GAAG,wBAAwB,CAAC;AAExC;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,MAAe;IAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACrE,MAAM,IAAI,UAAU,CAClB,yHAAyH,CAC1H,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,KAAa,EAAE,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,KAAK,CAAC;IACvF,MAAM,IAAI,SAAS,CAAC,OAAO,KAAK,0DAA0D,CAAC,CAAC;AAC9F,CAAC"}

package/dist/preferences/index.d.ts

@@ -0,0 +1,15 @@
+export type { EmailPreferencesDb } from './database.js';
+export { DEFAULT_SUPPRESSION_SCOPE, SUPPRESSION_REASONS, SqlSuppressionStore, suppressionStoreDdl } from './SuppressionStore.js';
+export type { SuppressionReason, SuppressionStore } from './SuppressionStore.js';
+export { SqlRecipientCapability, recipientCapabilityDdl } from './RecipientCapability.js';
+export type { RecipientCapability, RecipientCapabilityIssueOptions, RecipientGrant, SqlRecipientCapabilityOptions, } from './RecipientCapability.js';
+/**
+ * Both tables' DDL under one prefix, the suppression record's then the recipient capabilities', for a host whose one
+ * migration makes both. A host whose tables come from different migrations runs `suppressionStoreDdl` and
+ * `recipientCapabilityDdl` where each belongs.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+export declare function emailPreferencesDdl(prefix: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/preferences/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/preferences/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjI,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,YAAY,EACV,mBAAmB,EACnB,+BAA+B,EAC/B,cAAc,EACd,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAElC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/preferences/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recipientCapabilityDdl = exports.SqlRecipientCapability = exports.suppressionStoreDdl = exports.SqlSuppressionStore = exports.SUPPRESSION_REASONS = exports.DEFAULT_SUPPRESSION_SCOPE = void 0;
+exports.emailPreferencesDdl = emailPreferencesDdl;
+/**
+ * @fileoverview The email pack's preference stores: the suppression record and recipient capabilities, each on a
+ * host's SQL database under a table prefix.
+ */
+const RecipientCapability_js_1 = require("./RecipientCapability.js");
+const SuppressionStore_js_1 = require("./SuppressionStore.js");
+var SuppressionStore_js_2 = require("./SuppressionStore.js");
+Object.defineProperty(exports, "DEFAULT_SUPPRESSION_SCOPE", { enumerable: true, get: function () { return SuppressionStore_js_2.DEFAULT_SUPPRESSION_SCOPE; } });
+Object.defineProperty(exports, "SUPPRESSION_REASONS", { enumerable: true, get: function () { return SuppressionStore_js_2.SUPPRESSION_REASONS; } });
+Object.defineProperty(exports, "SqlSuppressionStore", { enumerable: true, get: function () { return SuppressionStore_js_2.SqlSuppressionStore; } });
+Object.defineProperty(exports, "suppressionStoreDdl", { enumerable: true, get: function () { return SuppressionStore_js_2.suppressionStoreDdl; } });
+var RecipientCapability_js_2 = require("./RecipientCapability.js");
+Object.defineProperty(exports, "SqlRecipientCapability", { enumerable: true, get: function () { return RecipientCapability_js_2.SqlRecipientCapability; } });
+Object.defineProperty(exports, "recipientCapabilityDdl", { enumerable: true, get: function () { return RecipientCapability_js_2.recipientCapabilityDdl; } });
+/**
+ * Both tables' DDL under one prefix, the suppression record's then the recipient capabilities', for a host whose one
+ * migration makes both. A host whose tables come from different migrations runs `suppressionStoreDdl` and
+ * `recipientCapabilityDdl` where each belongs.
+ *
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @throws RangeError when the prefix does not fit.
+ */
+function emailPreferencesDdl(prefix) {
+    return `${(0, SuppressionStore_js_1.suppressionStoreDdl)(prefix)}\n${(0, RecipientCapability_js_1.recipientCapabilityDdl)(prefix)}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/preferences/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/preferences/index.ts"],"names":[],"mappings":";;;AA0BA,kDAEC;AA5BD;;;GAGG;AACH,qEAAkE;AAClE,+DAA4D;AAG5D,6DAAiI;AAAxH,gIAAA,yBAAyB,OAAA;AAAE,0HAAA,mBAAmB,OAAA;AAAE,0HAAA,mBAAmB,OAAA;AAAE,0HAAA,mBAAmB,OAAA;AAEjG,mEAA0F;AAAjF,gIAAA,sBAAsB,OAAA;AAAE,gIAAA,sBAAsB,OAAA;AAQvD;;;;;;;GAOG;AACH,SAAgB,mBAAmB,CAAC,MAAc;IAChD,OAAO,GAAG,IAAA,yCAAmB,EAAC,MAAM,CAAC,KAAK,IAAA,+CAAsB,EAAC,MAAM,CAAC,EAAE,CAAC;AAC7E,CAAC"}

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
   "id": "com.framers.channels.email",
   "name": "Email Channel Extension",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Bidirectional email integration: send through SMTP or Resend's HTTPS API, and read, search, extract verification codes and reply through IMAP.",
   "categories": ["channel", "communication"],
   "platforms": ["email"],
@@ -22,6 +22,7 @@
     "Read inbox and other IMAP folders",
     "Search emails by query, folder, and date range",
     "Extract verification codes and OTPs from email bodies",
-    "Reply to email threads maintaining conversation context"
+    "Reply to email threads maintaining conversation context",
+    "Keep a suppression record and opaque unsubscribe tokens, stored as hashes, on a SQL database"
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@framers/agentos-ext-channel-email",
-  "version": "0.3.0",
-  "description": "Email channel adapter for AgentOS: send through SMTP or Resend's HTTPS API, and read, search, extract codes and reply through IMAP.",
+  "version": "0.4.1",
+  "description": "Email channel adapter for AgentOS: send through SMTP or Resend's HTTPS API; read, search, extract codes and reply through IMAP; keep a suppression record and unsubscribe tokens on a SQL database.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -22,6 +22,7 @@
     "nodemailer": "^10.0.16"
   },
   "devDependencies": {
+    "@framers/sql-storage-adapter": "^0.6.14",
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.7",