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

package/dist/preferences/SuppressionStore.d.ts

@@ -1,11 +1,14 @@
 /**
- * @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
+ * @fileoverview The suppression record: the addresses a host must not mail, by scope, each named by a hash of the
+ * address that the host computes, such as its SHA-256, 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. */
+/**
+ * The reasons an address is suppressed, in the order the README lists them. The store checks a reason against this
+ * list, so it is frozen: no caller can widen it or empty it.
+ */
 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
@@ -17,37 +20,42 @@ export type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
 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.
+ * domain's, and most hosts keep one, `DEFAULT_SUPPRESSION_SCOPE`. An address is named by its hash, 64 lower-case
+ * hexadecimal characters, which the host computes the same way wherever it reads or writes the record, such as the
+ * SHA-256 of 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. A plain SHA-256 lets anyone who holds the table check an address
+ * they guess; a host that wants the table to tell nothing of an address it does not already hold computes HMAC-SHA256
+ * under a key of its own instead.
  */
 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.
+     * @param scope The list: 1 to 512 UTF-16 code units, with no U+0000 and no lone surrogate.
+     * @param addressHash The address's hash 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 scope The list: 1 to 512 UTF-16 code units, with no U+0000 and no lone surrogate.
+     * @param addressHash The address's hash 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.
+     * @returns `true` when this call recorded the address, `false` when the scope held it already; `false` whatever the
+     * call wrote when the database's `run` answers no count of `changes`.
      */
     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.
+ * the reason and the day, `CREATE TABLE IF NOT EXISTS` so a migration can run it again. It runs on SQLite and on
+ * PostgreSQL, from one process at a time: PostgreSQL does not promise that two processes making one new table at once
+ * both succeed.
  *
- * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores, other than
+ * `sqlite` and a prefix beginning `sqlite_`.
  * @throws RangeError when the prefix does not fit.
  */
 export declare function suppressionStoreDdl(prefix: string): string;

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

@@ -1 +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"}
+{"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;;;GAGG;AACH,eAAO,MAAM,mBAAmB,0DAA0E,CAAC;AAE3G;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnE;;;;;;;;;;OAUG;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;;;;;;;;;GASG;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

@@ -3,11 +3,14 @@ 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 reasons an address is suppressed, in the order the README lists them. The store checks a reason against this
+ * list, so it is frozen: no caller can widen it or empty it.
+ */
+exports.SUPPRESSION_REASONS = Object.freeze(['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. */
+/** An address's hash, such as its SHA-256, 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})$/;
@@ -18,7 +21,7 @@ const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
 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');
+    throw new TypeError("The address hash was refused: give the address's hash, such as its SHA-256, as 64 lower-case hexadecimal characters");
 }
 /** Returns the reason when it is one of `SUPPRESSION_REASONS`, and otherwise throws a `TypeError`. */
 function requireReason(value) {
@@ -31,20 +34,25 @@ function requireReason(value) {
 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;
+        if (parts !== null) {
+            // setUTCFullYear takes the year as written, where Date.UTC reads 0 to 99 as 1900 to 1999. A date that does not
+            // exist, such as the 30th of February, comes back as another day.
+            const date = new Date(0);
+            date.setUTCFullYear(Number(parts[1]), Number(parts[2]) - 1, Number(parts[3]));
+            if (date.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.
+ * the reason and the day, `CREATE TABLE IF NOT EXISTS` so a migration can run it again. It runs on SQLite and on
+ * PostgreSQL, from one process at a time: PostgreSQL does not promise that two processes making one new table at once
+ * both succeed.
  *
- * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores.
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores, other than
+ * `sqlite` and a prefix beginning `sqlite_`.
  * @throws RangeError when the prefix does not fit.
  */
 function suppressionStoreDdl(prefix) {
@@ -84,7 +92,7 @@ class SqlSuppressionStore {
         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;
+        return (0, database_js_1.changesOf)(result) === 1;
     }
 }
 exports.SqlSuppressionStore = SqlSuppressionStore;

package/dist/preferences/SuppressionStore.js.map

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

package/dist/preferences/database.d.ts

@@ -9,23 +9,39 @@
  * 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. */
+    /**
+     * Runs one statement; `changes` is the number of rows it inserted, updated or deleted. A handle whose answer holds no
+     * such count, because it leaves `changes` out or gives something other than a whole number of 0 or more, still
+     * records, issues and revokes, but then `suppress` answers `false` and `revoke` answers 0 whatever they wrote.
+     */
     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>;
 }
+/**
+ * The rows a statement wrote, as its handle's `run` answered them: `changes` when it is a whole number of 0 or more, and
+ * otherwise 0. An answer that is no count never passes for one, such as text, NaN, -1 or the object the storage
+ * adapter's Capacitor handle answered before 0.6.14 (`{ changes: { changes, lastId } }`).
+ *
+ * @param result What the handle's `run` answered.
+ */
+export declare function changesOf(result: {
+    readonly changes?: unknown;
+} | null | undefined): number;
 /**
  * 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.
+ * other than `sqlite` and a prefix beginning `sqlite_`, and otherwise throws a `RangeError`. The prefix is written into
+ * the SQL as it is, so nothing else passes, and every prefix that passes makes tables on SQLite and on PostgreSQL.
  *
  * @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.
+ * Returns `value` when it is a string of 1 to 512 UTF-16 code units (its `length`, in which a character past U+FFFF
+ * counts two) that a text column holds as it is, with no U+0000 and no lone surrogate, 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.

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

@@ -1 +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"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/preferences/database.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,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;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAG3F;AAWD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAMrD;AAUD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKjE"}

package/dist/preferences/database.js

@@ -4,31 +4,58 @@
  * take. Nothing here imports a database driver: the host passes its own handle.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.changesOf = changesOf;
 exports.requirePrefix = requirePrefix;
 exports.requireName = requireName;
+/**
+ * The rows a statement wrote, as its handle's `run` answered them: `changes` when it is a whole number of 0 or more, and
+ * otherwise 0. An answer that is no count never passes for one, such as text, NaN, -1 or the object the storage
+ * adapter's Capacitor handle answered before 0.6.14 (`{ changes: { changes, lastId } }`).
+ *
+ * @param result What the handle's `run` answered.
+ */
+function changesOf(result) {
+    const changes = result?.changes;
+    return typeof changes === 'number' && Number.isSafeInteger(changes) && changes >= 0 ? changes : 0;
+}
 /** 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}$/;
+/**
+ * A prefix whose tables would begin `sqlite_`: SQLite keeps those names for its own tables and refuses to create one
+ * (https://www.sqlite.org/lang_createtable.html).
+ */
+const SQLITE_OWN = /^sqlite(?:_|$)/;
 /**
  * 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.
+ * other than `sqlite` and a prefix beginning `sqlite_`, and otherwise throws a `RangeError`. The prefix is written into
+ * the SQL as it is, so nothing else passes, and every prefix that passes makes tables on SQLite and on PostgreSQL.
  *
  * @param prefix The table prefix the caller gave.
  */
 function requirePrefix(prefix) {
-    if (typeof prefix === 'string' && PREFIX.test(prefix))
+    if (typeof prefix === 'string' && PREFIX.test(prefix) && !SQLITE_OWN.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');
+    throw new RangeError('The table prefix was refused: give a lower-case letter followed by at most 39 lower-case letters, digits or ' +
+        'underscores, other than sqlite and a prefix beginning sqlite_, whose tables SQLite keeps for itself');
 }
 /**
- * Returns `value` when it is a string of 1 to 512 characters, and otherwise throws a `TypeError` that names `field` and
- * never the value.
+ * What a text column cannot hold as given: U+0000, which PostgreSQL's text refuses, and a lone surrogate, which UTF-8
+ * cannot encode, so a driver writes something else in its place (node-postgres writes U+FFFD): the row would name
+ * another value, and two values would meet in one. With the `u` flag a surrogate pair is one code point and does not
+ * match.
+ */
+const UNSTORABLE = /\u0000|[\uD800-\uDFFF]/u;
+/**
+ * Returns `value` when it is a string of 1 to 512 UTF-16 code units (its `length`, in which a character past U+FFFF
+ * counts two) that a text column holds as it is, with no U+0000 and no lone surrogate, 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)
+    if (typeof value === 'string' && value.length > 0 && value.length <= 512 && !UNSTORABLE.test(value))
         return value;
-    throw new TypeError(`The ${field} was refused: give it as a string of 1 to 512 characters`);
+    throw new TypeError(`The ${field} was refused: give it as a string of 1 to 512 UTF-16 code units with no U+0000 and no lone surrogate`);
 }
 //# sourceMappingURL=database.js.map

package/dist/preferences/database.js.map

@@ -1 +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"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/preferences/database.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA0BH,8BAGC;AAkBD,sCAMC;AAkBD,kCAKC;AAzDD;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,MAAyD;IACjF,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,CAAC;IAChC,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AACpG,CAAC;AAED,sGAAsG;AACtG,MAAM,MAAM,GAAG,wBAAwB,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAEpC;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,MAAe;IAC3C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACjG,MAAM,IAAI,UAAU,CAClB,8GAA8G;QAC5G,qGAAqG,CACxG,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAE7C;;;;;;;GAOG;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,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAClH,MAAM,IAAI,SAAS,CACjB,OAAO,KAAK,sGAAsG,CACnH,CAAC;AACJ,CAAC"}

package/dist/preferences/index.d.ts

@@ -8,7 +8,8 @@ export type { RecipientCapability, RecipientCapabilityIssueOptions, RecipientGra
  * 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.
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores, other than
+ * `sqlite` and a prefix beginning `sqlite_`.
  * @throws RangeError when the prefix does not fit.
  */
 export declare function emailPreferencesDdl(prefix: string): string;

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

@@ -1 +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"}
+{"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;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/preferences/index.js

@@ -21,7 +21,8 @@ Object.defineProperty(exports, "recipientCapabilityDdl", { enumerable: true, get
  * 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.
+ * @param prefix A lower-case letter followed by at most 39 lower-case letters, digits or underscores, other than
+ * `sqlite` and a prefix beginning `sqlite_`.
  * @throws RangeError when the prefix does not fit.
  */
 function emailPreferencesDdl(prefix) {

package/dist/preferences/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/preferences/index.ts"],"names":[],"mappings":";;;AA2BA,kDAEC;AA7BD;;;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;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAAC,MAAc;IAChD,OAAO,GAAG,IAAA,yCAAmB,EAAC,MAAM,CAAC,KAAK,IAAA,+CAAsB,EAAC,MAAM,CAAC,EAAE,CAAC;AAC7E,CAAC"}

package/dist/reads.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview What `EmailService`'s reads check before any mail is read, and the work they do over a message, bounded.
+ * `readInbox` and `searchEmails` take a `limit` that is a whole number of at least 1: for any other, `readInbox` would
+ * fetch a sequence number past the last message, which a server answers BAD, and `searchEmails` would give every match
+ * or the wrong ones. `searchEmails` takes a `since` that is an ISO 8601 date naming a day its month has, and searches
+ * from that day: imapflow leaves an invalid date out of the search, which then answers mail of every date, and `Date`
+ * rolls a day past its month's end over into the next month. `extractCodes` compiles a caller's pattern before it
+ * reads the message, runs it over the message for at most `PATTERN_TIME_LIMIT_MS`, and moves on past a match of empty
+ * text, so no pattern holds the process. A message's HTML part loses its tags in one pass, in time growing with its
+ * length.
+ */
+/** The longest a caller's pattern may run over one message, in milliseconds. */
+export declare const PATTERN_TIME_LIMIT_MS = 250;
+/**
+ * `limit` when it is a whole number of at least 1, and `fallback` when it is `undefined` or `null`. Anything else, `0`,
+ * a negative or fractional number, `NaN`, `Infinity` and text among them, throws an `Error` before any mail is read.
+ *
+ * @param limit The most messages a read gives, as the caller gave it.
+ * @param fallback The limit when none is given.
+ */
+export declare function requireLimit(limit: unknown, fallback: number): number;
+/**
+ * The day a search starts from, as `YYYY-MM-DD`: the date `since` names, as written, or `undefined` when `since` is
+ * `undefined`, `null` or the empty string, for no bound. `since` is an ISO 8601 date, such as `2026-10-15`, alone or
+ * followed by a time and an offset, such as `2026-10-15T09:30:00-05:00`, which are checked and then disregarded.
+ * Anything else throws an `Error` before any mail is read: a value that is not text, a number among them; text in
+ * another form, which `Date` reads by guesswork and in the local time zone; and a day its month lacks, such as
+ * `2026-02-30`, which `Date` rolls over into the next month.
+ *
+ * @param since The day to search from, as the caller gave it.
+ */
+export declare function requireSince(since: unknown): string | undefined;
+/**
+ * `pattern` compiled as a JavaScript regular expression with the `g` flag, or `undefined` when it is `undefined`, `null`
+ * or the empty string, for the default. A pattern that is not a string throws a `TypeError`, and one that does not
+ * compile an `Error` holding the compiler's message, both before any mail is read.
+ *
+ * @param pattern The pattern as the caller gave it.
+ */
+export declare function requirePattern(pattern: unknown): RegExp | undefined;
+/**
+ * The codes `pattern` finds in `text`, in the order found: each match's first group, or the whole match when that group
+ * takes no part in it, leaving out each that is empty. A match of empty text moves the search on by one character, as
+ * `String.prototype.matchAll` does. The search runs for at most `PATTERN_TIME_LIMIT_MS`, timed by a `node:vm` script's
+ * timeout, which V8 honours at each step back a regular expression takes; one that runs longer, such as `(\d+)+$` over
+ * a long run of digits, throws an `Error` that names the limit. The `vm` module serves as a timer here, not a sandbox:
+ * the pattern runs in this realm, and a regular expression runs no code of its own.
+ *
+ * @param pattern A pattern `requirePattern` compiled, with the `g` flag.
+ * @param text The message's text.
+ */
+export declare function codesMatching(pattern: RegExp, text: string): string[];
+/**
+ * `html` with each tag written as a space, a tag running from a `<` to the first `>` after it with at least one
+ * character between them, as `/<[^>]+>/g` reads one: `<>` is no tag, and neither is a `<` with no `>` after it, and
+ * both stay in the text. The tags are found in one pass, in time growing with the length of `html`, where that
+ * expression takes time growing with the square of a run of `<` with no `>` after it.
+ *
+ * @param html The HTML part's text.
+ */
+export declare function withoutTags(html: string): string;
+/**
+ * A message's date as ISO 8601 text: the `Date` imapflow read from its Date field, or the empty string when the field
+ * is missing or does not read as a date, in which case imapflow gives the field's text instead.
+ *
+ * @param date The envelope's `date` as imapflow gives it.
+ */
+export declare function isoDateOf(date: unknown): string;
+//# sourceMappingURL=reads.d.ts.map

package/dist/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../src/reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrE;AAeD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAc/D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQnE;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAmBrE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBhD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAE/C"}

package/dist/reads.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * @fileoverview What `EmailService`'s reads check before any mail is read, and the work they do over a message, bounded.
+ * `readInbox` and `searchEmails` take a `limit` that is a whole number of at least 1: for any other, `readInbox` would
+ * fetch a sequence number past the last message, which a server answers BAD, and `searchEmails` would give every match
+ * or the wrong ones. `searchEmails` takes a `since` that is an ISO 8601 date naming a day its month has, and searches
+ * from that day: imapflow leaves an invalid date out of the search, which then answers mail of every date, and `Date`
+ * rolls a day past its month's end over into the next month. `extractCodes` compiles a caller's pattern before it
+ * reads the message, runs it over the message for at most `PATTERN_TIME_LIMIT_MS`, and moves on past a match of empty
+ * text, so no pattern holds the process. A message's HTML part loses its tags in one pass, in time growing with its
+ * length.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PATTERN_TIME_LIMIT_MS = void 0;
+exports.requireLimit = requireLimit;
+exports.requireSince = requireSince;
+exports.requirePattern = requirePattern;
+exports.codesMatching = codesMatching;
+exports.withoutTags = withoutTags;
+exports.isoDateOf = isoDateOf;
+const node_vm_1 = require("node:vm");
+const messageText_js_1 = require("./messageText.js");
+/** The longest a caller's pattern may run over one message, in milliseconds. */
+exports.PATTERN_TIME_LIMIT_MS = 250;
+/**
+ * `limit` when it is a whole number of at least 1, and `fallback` when it is `undefined` or `null`. Anything else, `0`,
+ * a negative or fractional number, `NaN`, `Infinity` and text among them, throws an `Error` before any mail is read.
+ *
+ * @param limit The most messages a read gives, as the caller gave it.
+ * @param fallback The limit when none is given.
+ */
+function requireLimit(limit, fallback) {
+    if (limit === undefined || limit === null)
+        return fallback;
+    if (typeof limit === 'number' && Number.isSafeInteger(limit) && limit >= 1)
+        return limit;
+    throw new Error('The limit was refused: give it as a whole number of at least 1');
+}
+/**
+ * An ISO 8601 calendar date, alone or followed by a time and an offset, in the forms ECMAScript's date time string
+ * format writes: `2026-10-15`, `2026-10-15T09:30`, `2026-10-15T09:30:00`, `2026-10-15T09:30:00.000`, each of the last
+ * three with `Z` or an offset such as `-05:00` after it or not.
+ */
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})?)?$/;
+/** The days of `month`, from 1 to 12, in `year` of the Gregorian calendar. */
+function daysIn(year, month) {
+    if (month === 2)
+        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28;
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+/**
+ * The day a search starts from, as `YYYY-MM-DD`: the date `since` names, as written, or `undefined` when `since` is
+ * `undefined`, `null` or the empty string, for no bound. `since` is an ISO 8601 date, such as `2026-10-15`, alone or
+ * followed by a time and an offset, such as `2026-10-15T09:30:00-05:00`, which are checked and then disregarded.
+ * Anything else throws an `Error` before any mail is read: a value that is not text, a number among them; text in
+ * another form, which `Date` reads by guesswork and in the local time zone; and a day its month lacks, such as
+ * `2026-02-30`, which `Date` rolls over into the next month.
+ *
+ * @param since The day to search from, as the caller gave it.
+ */
+function requireSince(since) {
+    if (since === undefined || since === null || since === '')
+        return undefined;
+    const parts = typeof since === 'string' ? ISO_DATE.exec(since) : null;
+    if (parts !== null) {
+        const year = Number(parts[1]);
+        const month = Number(parts[2]);
+        const day = Number(parts[3]);
+        // Date takes a day from 1 to 31 in any month and rolls one past the month's end over into the next, so the day is
+        // checked against its month here; Date checks the time and the offset.
+        if (month >= 1 && month <= 12 && day >= 1 && day <= daysIn(year, month) && !Number.isNaN(Date.parse(parts[0]))) {
+            return parts[0].slice(0, 10);
+        }
+    }
+    throw new Error('The since date was refused: give it as a date, such as 2026-10-15');
+}
+/**
+ * `pattern` compiled as a JavaScript regular expression with the `g` flag, or `undefined` when it is `undefined`, `null`
+ * or the empty string, for the default. A pattern that is not a string throws a `TypeError`, and one that does not
+ * compile an `Error` holding the compiler's message, both before any mail is read.
+ *
+ * @param pattern The pattern as the caller gave it.
+ */
+function requirePattern(pattern) {
+    const source = (0, messageText_js_1.optionalText)('pattern', pattern);
+    if (source === undefined || source === '')
+        return undefined;
+    try {
+        return new RegExp(source, 'g');
+    }
+    catch (error) {
+        throw new Error(`The pattern was refused: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** The script `codesMatching` runs its search in, so that the search has a time limit. */
+const UNDER_A_TIME_LIMIT = new node_vm_1.Script('found = search()');
+/**
+ * The codes `pattern` finds in `text`, in the order found: each match's first group, or the whole match when that group
+ * takes no part in it, leaving out each that is empty. A match of empty text moves the search on by one character, as
+ * `String.prototype.matchAll` does. The search runs for at most `PATTERN_TIME_LIMIT_MS`, timed by a `node:vm` script's
+ * timeout, which V8 honours at each step back a regular expression takes; one that runs longer, such as `(\d+)+$` over
+ * a long run of digits, throws an `Error` that names the limit. The `vm` module serves as a timer here, not a sandbox:
+ * the pattern runs in this realm, and a regular expression runs no code of its own.
+ *
+ * @param pattern A pattern `requirePattern` compiled, with the `g` flag.
+ * @param text The message's text.
+ */
+function codesMatching(pattern, text) {
+    const search = () => {
+        const codes = [];
+        for (const match of text.matchAll(pattern)) {
+            const code = match[1] ?? match[0];
+            if (code !== '')
+                codes.push(code);
+        }
+        return codes;
+    };
+    const context = (0, node_vm_1.createContext)({ search, found: undefined });
+    try {
+        UNDER_A_TIME_LIMIT.runInContext(context, { timeout: exports.PATTERN_TIME_LIMIT_MS });
+    }
+    catch (error) {
+        if (error?.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT') {
+            throw new Error(`The pattern was refused: it ran longer than ${exports.PATTERN_TIME_LIMIT_MS} ms over the message`);
+        }
+        throw error;
+    }
+    return context.found ?? [];
+}
+/**
+ * `html` with each tag written as a space, a tag running from a `<` to the first `>` after it with at least one
+ * character between them, as `/<[^>]+>/g` reads one: `<>` is no tag, and neither is a `<` with no `>` after it, and
+ * both stay in the text. The tags are found in one pass, in time growing with the length of `html`, where that
+ * expression takes time growing with the square of a run of `<` with no `>` after it.
+ *
+ * @param html The HTML part's text.
+ */
+function withoutTags(html) {
+    const pieces = [];
+    let copied = 0;
+    let open = html.indexOf('<');
+    while (open !== -1) {
+        const close = html.indexOf('>', open + 1);
+        // No ">" after this "<" means none after any later "<" either.
+        if (close === -1)
+            break;
+        if (close === open + 1) {
+            open = html.indexOf('<', close);
+            continue;
+        }
+        pieces.push(html.slice(copied, open), ' ');
+        copied = close + 1;
+        open = html.indexOf('<', copied);
+    }
+    pieces.push(html.slice(copied));
+    return pieces.join('');
+}
+/**
+ * A message's date as ISO 8601 text: the `Date` imapflow read from its Date field, or the empty string when the field
+ * is missing or does not read as a date, in which case imapflow gives the field's text instead.
+ *
+ * @param date The envelope's `date` as imapflow gives it.
+ */
+function isoDateOf(date) {
+    return date instanceof Date && !Number.isNaN(date.getTime()) ? date.toISOString() : '';
+}
+//# sourceMappingURL=reads.js.map

package/dist/reads.js.map

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

package/dist/tools/extractCodes.d.ts

@@ -23,6 +23,11 @@ export declare class EmailExtractCodesTool {
         required: string[];
     };
     constructor(service: EmailService);
+    /**
+     * Extracts the codes through `EmailService.extractCodes`. A `pattern` that is not a string or does not compile is
+     * refused before any mail is read, and one that runs longer than 250 ms over the message is stopped, each with
+     * `{ success: false, error }`.
+     */
     execute(args: {
         messageId: string;
         pattern?: string;

package/dist/tools/extractCodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractCodes.d.ts","sourceRoot":"","sources":["../../src/tools/extractCodes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,qBAAa,qBAAqB;IAkBpB,OAAO,CAAC,OAAO;IAjB3B,QAAQ,CAAC,EAAE,uBAAuB;IAClC,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,WAAW,gCAAgC;IACpD,QAAQ,CAAC,WAAW,mFAAmF;IACvG,QAAQ,CAAC,QAAQ,mBAAmB;IACpC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,cAAc,SAAS;IAEhC,QAAQ,CAAC,WAAW;;;;;;;;;;;;;MAOlB;gBAEkB,OAAO,EAAE,YAAY;IAEnC,OAAO,CAAC,IAAI,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ9D"}
+{"version":3,"file":"extractCodes.d.ts","sourceRoot":"","sources":["../../src/tools/extractCodes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,qBAAa,qBAAqB;IAsBpB,OAAO,CAAC,OAAO;IArB3B,QAAQ,CAAC,EAAE,uBAAuB;IAClC,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,WAAW,gCAAgC;IACpD,QAAQ,CAAC,WAAW,mFAAmF;IACvG,QAAQ,CAAC,QAAQ,mBAAmB;IACpC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,cAAc,SAAS;IAEhC,QAAQ,CAAC,WAAW;;;;;;;;;;;;;MAWlB;gBAEkB,OAAO,EAAE,YAAY;IAEzC;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ9D"}

package/dist/tools/extractCodes.js

@@ -14,12 +14,20 @@ class EmailExtractCodesTool {
         this.inputSchema = {
             type: 'object',
             properties: {
-                messageId: { type: 'string', description: 'Message ID of the email to extract codes from' },
-                pattern: { type: 'string', description: 'Optional regex pattern to match codes (default: 4-8 digit numbers)' },
+                messageId: { type: 'string', description: 'Message ID of the email to extract codes from, as emailRead or emailSearch gives it, such as <id@example.com>' },
+                pattern: {
+                    type: 'string',
+                    description: "Optional JavaScript regular expression for the codes: each match's first group, or the whole match, is a code. It runs for at most 250 ms (default: runs of 4 to 8 digits)",
+                },
             },
             required: ['messageId'],
         };
     }
+    /**
+     * Extracts the codes through `EmailService.extractCodes`. A `pattern` that is not a string or does not compile is
+     * refused before any mail is read, and one that runs longer than 250 ms over the message is stopped, each with
+     * `{ success: false, error }`.
+     */
     async execute(args) {
         try {
             const result = await this.service.extractCodes(args.messageId, args.pattern);