@askeleven/sms-guard 0.1.0

package/types/index.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Checks one text message before it is sent: how many segments it will be, what
+ * forces it into UCS-2, whether it lands inside the recipient's allowed hours, and
+ * a few things carriers and recipients object to. Runs locally, touches no network.
+ *
+ * @param {string} text
+ * @param {CheckOptions} [options]
+ * @returns {Result}
+ */
+export function checkMessage(text: string, options?: CheckOptions): Result;
+/**
+ * Shows invisible and whitespace characters by code point, the rest as themselves.
+ *
+ * @param {Ucs2Character} c
+ * @returns {string}
+ */
+export function displayChar(c: Ucs2Character): string;
+export { parseNumber } from "./phone.js";
+/**
+ * @typedef {import('./segments.js').Encoding} Encoding
+ * @typedef {import('./segments.js').SegmentCount} SegmentCount
+ * @typedef {import('./segments.js').Ucs2Character} Ucs2Character
+ * @typedef {import('./split.js').Part} Part
+ * @typedef {import('./split.js').SplitOptions} SplitOptions
+ * @typedef {import('./phone.js').LocalTime} LocalTime
+ *
+ * @typedef {'keep'|'review'|'fail'} Verdict
+ *
+ * @typedef {'empty'|'too_many_segments'|'invalid_number'|'quiet_hours'
+ *   |'timezone_ambiguous'|'timezone_unknown'|'url_shortener'|'no_opt_out'
+ *   |'ucs2'} ReasonCode
+ *
+ * @typedef {object} Reason
+ * @property {ReasonCode} code Stable, safe to match on.
+ * @property {Verdict} verdict What this reason alone would make of the message.
+ * @property {string} detail Plain English.
+ *
+ * @typedef {object} Recipient
+ * @property {string} input As given.
+ * @property {string | null} number E.164, or null when it could not be read.
+ * @property {boolean} assumedNanp Read as +1 because it had no country code and
+ *   10 digits (or 11 starting with 1).
+ * @property {string | null} region State, province or country, when known.
+ * @property {string[]} timezones Every IANA zone the number could be in.
+ * @property {string | null} timezone The zone, when there is exactly one.
+ * @property {Array<LocalTime & { inWindow: boolean }>} local Local send time in each
+ *   of the zones.
+ * @property {boolean | null} inWindow Whether the send time is inside the window in
+ *   every zone; null when no zone is known.
+ * @property {string | null} nextWindowStart ISO 8601, the first minute after the send
+ *   time that is inside the window in every zone, when the send time is not.
+ *
+ * @typedef {object} Facts
+ * @property {Encoding} encoding
+ * @property {number} characters Unicode code points.
+ * @property {number} units Septets for GSM-7, UTF-16 code units for UCS-2.
+ * @property {number} segments
+ * @property {number} perSegment Units per segment at this length.
+ * @property {number} maxSegments
+ * @property {Ucs2Character[]} ucs2Characters What forces UCS-2, if anything.
+ * @property {string} sendAt ISO 8601.
+ * @property {string} window HH:MM-HH:MM, recipient local time.
+ * @property {'checked'|'skipped'} timeCheck Whether the send time was checked
+ *   against the recipient's local time. Skipped with no recipient, or when their
+ *   time zone is not known.
+ * @property {Recipient | null} recipient
+ *
+ * @typedef {object} Result
+ * @property {Verdict} verdict The worst verdict among the reasons; 'keep' with none.
+ * @property {Reason[]} reasons
+ * @property {Facts} facts
+ * @property {string[]} notes What the reader needs to know to trust the result,
+ *   such as checks that did not run.
+ *
+ * @typedef {object} CheckOptions
+ * @property {string} [to] Recipient phone number, E.164 preferred.
+ * @property {Date | string | number} [sendAt] When it will be sent. A string must be
+ *   ISO 8601 with an offset or Z. Default now.
+ * @property {number} [maxSegments] Fail above this many segments. Default 5.
+ * @property {string} [window] Allowed local send time, HH:MM-HH:MM, start inclusive,
+ *   end exclusive. Default 08:00-21:00.
+ * @property {boolean} [firstMessage] The first text to this person: look for opt-out
+ *   wording. Default false.
+ * @property {Date | (() => Date)} [now] The clock, for tests.
+ */
+export const DEFAULT_WINDOW: "08:00-21:00";
+export class GuardError extends Error {
+    /**
+     * @param {'invalid_option'} code
+     * @param {string} message
+     */
+    constructor(code: "invalid_option", message: string);
+    code: "invalid_option";
+}
+export type Encoding = import("./segments.js").Encoding;
+export type SegmentCount = import("./segments.js").SegmentCount;
+export type Ucs2Character = import("./segments.js").Ucs2Character;
+export type Part = import("./split.js").Part;
+export type SplitOptions = import("./split.js").SplitOptions;
+export type LocalTime = import("./phone.js").LocalTime;
+export type Verdict = "keep" | "review" | "fail";
+export type ReasonCode = "empty" | "too_many_segments" | "invalid_number" | "quiet_hours" | "timezone_ambiguous" | "timezone_unknown" | "url_shortener" | "no_opt_out" | "ucs2";
+export type Reason = {
+    /**
+     * Stable, safe to match on.
+     */
+    code: ReasonCode;
+    /**
+     * What this reason alone would make of the message.
+     */
+    verdict: Verdict;
+    /**
+     * Plain English.
+     */
+    detail: string;
+};
+export type Recipient = {
+    /**
+     * As given.
+     */
+    input: string;
+    /**
+     * E.164, or null when it could not be read.
+     */
+    number: string | null;
+    /**
+     * Read as +1 because it had no country code and
+     * 10 digits (or 11 starting with 1).
+     */
+    assumedNanp: boolean;
+    /**
+     * State, province or country, when known.
+     */
+    region: string | null;
+    /**
+     * Every IANA zone the number could be in.
+     */
+    timezones: string[];
+    /**
+     * The zone, when there is exactly one.
+     */
+    timezone: string | null;
+    /**
+     * Local send time in each
+     * of the zones.
+     */
+    local: Array<LocalTime & {
+        inWindow: boolean;
+    }>;
+    /**
+     * Whether the send time is inside the window in
+     * every zone; null when no zone is known.
+     */
+    inWindow: boolean | null;
+    /**
+     * ISO 8601, the first minute after the send
+     * time that is inside the window in every zone, when the send time is not.
+     */
+    nextWindowStart: string | null;
+};
+export type Facts = {
+    encoding: Encoding;
+    /**
+     * Unicode code points.
+     */
+    characters: number;
+    /**
+     * Septets for GSM-7, UTF-16 code units for UCS-2.
+     */
+    units: number;
+    segments: number;
+    /**
+     * Units per segment at this length.
+     */
+    perSegment: number;
+    maxSegments: number;
+    /**
+     * What forces UCS-2, if anything.
+     */
+    ucs2Characters: Ucs2Character[];
+    /**
+     * ISO 8601.
+     */
+    sendAt: string;
+    /**
+     * HH:MM-HH:MM, recipient local time.
+     */
+    window: string;
+    /**
+     * Whether the send time was checked
+     * against the recipient's local time. Skipped with no recipient, or when their
+     * time zone is not known.
+     */
+    timeCheck: "checked" | "skipped";
+    recipient: Recipient | null;
+};
+export type Result = {
+    /**
+     * The worst verdict among the reasons; 'keep' with none.
+     */
+    verdict: Verdict;
+    reasons: Reason[];
+    facts: Facts;
+    /**
+     * What the reader needs to know to trust the result,
+     * such as checks that did not run.
+     */
+    notes: string[];
+};
+export type CheckOptions = {
+    /**
+     * Recipient phone number, E.164 preferred.
+     */
+    to?: string | undefined;
+    /**
+     * When it will be sent. A string must be
+     * ISO 8601 with an offset or Z. Default now.
+     */
+    sendAt?: string | number | Date | undefined;
+    /**
+     * Fail above this many segments. Default 5.
+     */
+    maxSegments?: number | undefined;
+    /**
+     * Allowed local send time, HH:MM-HH:MM, start inclusive,
+     * end exclusive. Default 08:00-21:00.
+     */
+    window?: string | undefined;
+    /**
+     * The first text to this person: look for opt-out
+     * wording. Default false.
+     */
+    firstMessage?: boolean | undefined;
+    /**
+     * The clock, for tests.
+     */
+    now?: Date | (() => Date) | undefined;
+};
+export { encodingOf, countSegments, ucs2Characters, LIMITS } from "./segments.js";
+export { splitMessage, DEFAULT_MAX_SEGMENTS } from "./split.js";

package/types/mcp.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @typedef {object} ServeOptions
+ * @property {NodeJS.ReadableStream} [input]
+ * @property {NodeJS.WritableStream} [output]
+ * @property {Partial<import('./index.js').CheckOptions>} [checkOptions] Overrides for
+ *   tests, such as a fixed clock.
+ */
+/**
+ * Serves until the input stream closes.
+ *
+ * @param {ServeOptions} [options]
+ * @returns {Promise<void>}
+ */
+export function serve(options?: ServeOptions): Promise<void>;
+export type ServeOptions = {
+    input?: NodeJS.ReadableStream | undefined;
+    output?: NodeJS.WritableStream | undefined;
+    /**
+     * Overrides for
+     * tests, such as a fixed clock.
+     */
+    checkOptions?: Partial<import("./index.js").CheckOptions> | undefined;
+};

package/types/phone.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Reads a phone number. Accepts E.164 with or without formatting (+1 (305) 555-0100,
+ * +44 20 7946 0000). Without a leading +, only a 10-digit number, or an 11-digit
+ * number starting with 1, is accepted, and it is read as NANP (US, Canada and the
+ * rest of +1). Anything else without a + is refused rather than guessed at.
+ *
+ * @param {string} raw
+ * @returns {{ ok: true, number: ParsedNumber } | { ok: false, error: string }}
+ */
+export function parseNumber(raw: string): {
+    ok: true;
+    number: ParsedNumber;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The time zone, or zones, a number could be in.
+ *
+ * @param {ParsedNumber} number
+ * @returns {ZoneLookup}
+ */
+export function zonesFor(number: ParsedNumber): ZoneLookup;
+/**
+ * @typedef {object} Window
+ * @property {number} start Minutes after local midnight, inclusive.
+ * @property {number} end Minutes after local midnight, exclusive.
+ * @property {string} label As given, HH:MM-HH:MM.
+ */
+/**
+ * Parses HH:MM-HH:MM. The start is inclusive and the end exclusive, so 08:00-21:00
+ * allows 08:00 and 20:59 but not 21:00. A window that wraps midnight (22:00-06:00)
+ * is allowed.
+ *
+ * @param {string} window
+ * @returns {Window | null}
+ */
+export function parseWindow(window: string): Window | null;
+/**
+ * @param {number} minutes Minutes after local midnight.
+ * @param {Window} window
+ * @returns {boolean}
+ */
+export function inWindow(minutes: number, window: Window): boolean;
+/**
+ * The wall-clock time in a zone, from the runtime's own time zone data.
+ *
+ * @param {Date} date
+ * @param {string} timezone
+ * @returns {LocalTime}
+ */
+export function localTime(date: Date, timezone: string): LocalTime;
+/**
+ * The first minute at or after `from` when it is inside the window in every one of
+ * the zones, or null if there is none in the next two days.
+ *
+ * @param {Date} from
+ * @param {string[]} zones
+ * @param {Window} window
+ * @returns {Date | null}
+ */
+export function nextWindowStart(from: Date, zones: string[], window: Window): Date | null;
+export type Window = {
+    /**
+     * Minutes after local midnight, inclusive.
+     */
+    start: number;
+    /**
+     * Minutes after local midnight, exclusive.
+     */
+    end: number;
+    /**
+     * As given, HH:MM-HH:MM.
+     */
+    label: string;
+};
+export type ParsedNumber = {
+    /**
+     * The number as +<digits>.
+     */
+    e164: string;
+    /**
+     * '1' for NANP, otherwise as matched in the country
+     * table, or an empty string when no row matches.
+     */
+    countryCode: string;
+    /**
+     * True when the number had no + and was read as a
+     * US or Canadian number because it had 10 digits (or 11 starting with 1).
+     */
+    assumedNanp: boolean;
+};
+export type ZoneLookup = {
+    /**
+     * State, province or country, when known.
+     */
+    region: string | null;
+    /**
+     * IANA zones. None means unknown; more than one, ambiguous.
+     */
+    zones: string[];
+    /**
+     * What the zones were worked out from, in plain English.
+     */
+    basis: string;
+};
+export type LocalTime = {
+    timezone: string;
+    /**
+     * Local wall-clock time, YYYY-MM-DDTHH:MM.
+     */
+    time: string;
+    /**
+     * Such as "Sun 19:30 EDT".
+     */
+    label: string;
+    /**
+     * Minutes after local midnight.
+     */
+    minutes: number;
+};

package/types/report.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @param {Result} result
+ * @param {{ colour?: boolean, width?: number }} [options]
+ * @returns {string}
+ */
+export function formatText(result: Result, options?: {
+    colour?: boolean;
+    width?: number;
+}): string;
+/**
+ * @param {Part[]} parts
+ * @param {{ maxSegments: number, colour?: boolean }} options
+ * @returns {string}
+ */
+export function formatSplit(parts: Part[], options: {
+    maxSegments: number;
+    colour?: boolean;
+}): string;
+export type Result = import("./index.js").Result;
+export type ReasonCode = import("./index.js").ReasonCode;
+export type Verdict = import("./index.js").Verdict;
+export type Part = import("./split.js").Part;

package/types/segments.d.ts

@@ -0,0 +1,115 @@
+/**
+ * GSM-7 when every character is in the default alphabet or its extension table,
+ * UCS-2 otherwise. One character outside both is enough to switch the whole message.
+ *
+ * @param {string} text
+ * @returns {Encoding}
+ */
+export function encodingOf(text: string): Encoding;
+/**
+ * What one character costs in the given encoding.
+ *
+ * @param {string} char One code point.
+ * @param {Encoding} encoding
+ * @returns {number}
+ */
+export function unitCost(char: string, encoding: Encoding): number;
+/**
+ * Counts segments the way the network does. A GSM-7 escape pair, or a UTF-16
+ * surrogate pair, is never cut across two parts: when it does not fit in what is left
+ * of a part, the part is sent short and the pair starts the next one.
+ *
+ * @param {string} text
+ * @returns {SegmentCount}
+ */
+export function countSegments(text: string): SegmentCount;
+/**
+ * The characters that force a message into UCS-2, each once, in order of first
+ * appearance, with a GSM-7 replacement where one reads the same.
+ *
+ * @param {string} text
+ * @returns {Ucs2Character[]}
+ */
+export function ucs2Characters(text: string): Ucs2Character[];
+/**
+ * Applies the typographic replacements, and nothing else.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function replaceTypographic(text: string): string;
+/**
+ * @param {string} char
+ * @returns {string}
+ */
+export function codePointOf(char: string): string;
+/**
+ * @typedef {'GSM-7'|'UCS-2'} Encoding
+ *
+ * @typedef {object} SegmentCount
+ * @property {Encoding} encoding
+ * @property {number} characters Unicode code points, what a person would count.
+ * @property {number} units What the network counts: septets for GSM-7 (an extension
+ *   character is two), UTF-16 code units for UCS-2 (an emoji is usually two).
+ * @property {number} segments Parts the message is sent as. 0 for an empty message.
+ * @property {number} perSegment Units that fit in each part: 160 or 70 alone, 153 or
+ *   67 once a message is split, since the rest of each part carries the header that
+ *   joins them back together.
+ *
+ * @typedef {object} Ucs2Character
+ * @property {string} char
+ * @property {string} codePoint As U+XXXX.
+ * @property {number} count Times it appears.
+ * @property {string | null} replacement A GSM-7 equivalent, offered only for
+ *   typographic characters such as curly quotes, dashes and odd spaces.
+ */
+/** Units per message: [single, per part once concatenated]. */
+export const LIMITS: {
+    'GSM-7': {
+        single: number;
+        part: number;
+    };
+    'UCS-2': {
+        single: number;
+        part: number;
+    };
+};
+export type Encoding = "GSM-7" | "UCS-2";
+export type SegmentCount = {
+    encoding: Encoding;
+    /**
+     * Unicode code points, what a person would count.
+     */
+    characters: number;
+    /**
+     * What the network counts: septets for GSM-7 (an extension
+     * character is two), UTF-16 code units for UCS-2 (an emoji is usually two).
+     */
+    units: number;
+    /**
+     * Parts the message is sent as. 0 for an empty message.
+     */
+    segments: number;
+    /**
+     * Units that fit in each part: 160 or 70 alone, 153 or
+     * 67 once a message is split, since the rest of each part carries the header that
+     * joins them back together.
+     */
+    perSegment: number;
+};
+export type Ucs2Character = {
+    char: string;
+    /**
+     * As U+XXXX.
+     */
+    codePoint: string;
+    /**
+     * Times it appears.
+     */
+    count: number;
+    /**
+     * A GSM-7 equivalent, offered only for
+     * typographic characters such as curly quotes, dashes and odd spaces.
+     */
+    replacement: string | null;
+};

package/types/split.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Splits a message into parts that each fit within maxSegments, to be sent in order
+ * as separate texts. Breaks at a blank line where it can, then a line, then a
+ * sentence, then a word, and only cuts inside a word when a single word is too long.
+ * Parts are packed greedily, so there are as few as the breaks allow. Whitespace at
+ * each break is dropped. A GSM-7 escape pair or a surrogate pair is never cut, since
+ * the text is only ever cut between whole characters.
+ *
+ * @param {string} text
+ * @param {SplitOptions} [options]
+ * @returns {Part[]} Empty for a message with nothing but whitespace.
+ */
+export function splitMessage(text: string, options?: SplitOptions): Part[];
+/**
+ * @typedef {import('./segments.js').Encoding} Encoding
+ *
+ * @typedef {object} Part
+ * @property {string} text
+ * @property {Encoding} encoding Worked out for this part alone: a part with no
+ *   accented letters can go back to GSM-7.
+ * @property {number} characters
+ * @property {number} units
+ * @property {number} segments
+ *
+ * @typedef {object} SplitOptions
+ * @property {number} [maxSegments] Most segments any one part may use. Default 5.
+ */
+export const DEFAULT_MAX_SEGMENTS: 5;
+export type Encoding = import("./segments.js").Encoding;
+export type Part = {
+    text: string;
+    /**
+     * Worked out for this part alone: a part with no
+     * accented letters can go back to GSM-7.
+     */
+    encoding: Encoding;
+    characters: number;
+    units: number;
+    segments: number;
+};
+export type SplitOptions = {
+    /**
+     * Most segments any one part may use. Default 5.
+     */
+    maxSegments?: number | undefined;
+};

package/types/version.d.ts

@@ -0,0 +1,2 @@
+/** The published version, read from package.json so there is one place to bump it. */
+export const VERSION: string;