@oxygen-agent/cli 1.1003.12 → 1.1010.644

package/node_modules/@oxygen/shared/dist/linkedin-country-timezones.js

@@ -0,0 +1,276 @@
+/**
+ * Primary IANA time zone for each LinkedIn country code.
+ *
+ * WHY: a LinkedIn sender's working hours and daily-quota rollover run in the
+ * account owner's local time. The only geo signal OXYGEN holds for a new
+ * account is the country the owner chose at connect ("where the account owner
+ * normally uses LinkedIn"), so that country picks the zone whenever no explicit
+ * timezone was stored. Without it every account ran on America/New_York and a
+ * German account was active 13:00–04:00 Berlin time.
+ *
+ * GENERATED once from ICU's region → zone data (`new Intl.Locale("und-XX")
+ * .timeZones`) for the codes in LINKEDIN_COUNTRIES, then frozen here so a Node
+ * upgrade cannot silently move an account's window. Countries spanning several
+ * zones carry the zone of their largest business population (US → New York,
+ * CA → Toronto, AU → Sydney, BR → São Paulo, RU → Moscow, …). Territories with
+ * no populated zone (AQ, BV, HM) are absent and fall back to the default. An
+ * explicit per-account timezone always wins over this table.
+ */
+export const LINKEDIN_COUNTRY_PRIMARY_TIME_ZONES = {
+    AD: "Europe/Andorra",
+    AE: "Asia/Dubai",
+    AF: "Asia/Kabul",
+    AG: "America/Antigua",
+    AI: "America/Anguilla",
+    AL: "Europe/Tirane",
+    AM: "Asia/Yerevan",
+    AO: "Africa/Luanda",
+    AR: "America/Argentina/Buenos_Aires",
+    AS: "Pacific/Pago_Pago",
+    AT: "Europe/Vienna",
+    AU: "Australia/Sydney",
+    AW: "America/Aruba",
+    AX: "Europe/Mariehamn",
+    AZ: "Asia/Baku",
+    BA: "Europe/Sarajevo",
+    BB: "America/Barbados",
+    BD: "Asia/Dhaka",
+    BE: "Europe/Brussels",
+    BF: "Africa/Ouagadougou",
+    BG: "Europe/Sofia",
+    BH: "Asia/Bahrain",
+    BI: "Africa/Bujumbura",
+    BJ: "Africa/Porto-Novo",
+    BL: "America/St_Barthelemy",
+    BM: "Atlantic/Bermuda",
+    BN: "Asia/Brunei",
+    BO: "America/La_Paz",
+    BQ: "America/Kralendijk",
+    BR: "America/Sao_Paulo",
+    BS: "America/Nassau",
+    BT: "Asia/Thimphu",
+    BW: "Africa/Gaborone",
+    BY: "Europe/Minsk",
+    BZ: "America/Belize",
+    CA: "America/Toronto",
+    CC: "Indian/Cocos",
+    CD: "Africa/Kinshasa",
+    CF: "Africa/Bangui",
+    CG: "Africa/Brazzaville",
+    CH: "Europe/Zurich",
+    CI: "Africa/Abidjan",
+    CK: "Pacific/Rarotonga",
+    CL: "America/Santiago",
+    CM: "Africa/Douala",
+    CN: "Asia/Shanghai",
+    CO: "America/Bogota",
+    CR: "America/Costa_Rica",
+    CU: "America/Havana",
+    CV: "Atlantic/Cape_Verde",
+    CW: "America/Curacao",
+    CX: "Indian/Christmas",
+    CY: "Asia/Nicosia",
+    CZ: "Europe/Prague",
+    DE: "Europe/Berlin",
+    DJ: "Africa/Djibouti",
+    DK: "Europe/Copenhagen",
+    DM: "America/Dominica",
+    DO: "America/Santo_Domingo",
+    DZ: "Africa/Algiers",
+    EC: "America/Guayaquil",
+    EE: "Europe/Tallinn",
+    EG: "Africa/Cairo",
+    EH: "Africa/El_Aaiun",
+    ER: "Africa/Asmara",
+    ES: "Europe/Madrid",
+    ET: "Africa/Addis_Ababa",
+    FI: "Europe/Helsinki",
+    FJ: "Pacific/Fiji",
+    FK: "Atlantic/Stanley",
+    FM: "Pacific/Pohnpei",
+    FO: "Atlantic/Faroe",
+    FR: "Europe/Paris",
+    GA: "Africa/Libreville",
+    GB: "Europe/London",
+    GD: "America/Grenada",
+    GE: "Asia/Tbilisi",
+    GF: "America/Cayenne",
+    GG: "Europe/Guernsey",
+    GH: "Africa/Accra",
+    GI: "Europe/Gibraltar",
+    GL: "America/Nuuk",
+    GM: "Africa/Banjul",
+    GN: "Africa/Conakry",
+    GP: "America/Guadeloupe",
+    GQ: "Africa/Malabo",
+    GR: "Europe/Athens",
+    GS: "Atlantic/South_Georgia",
+    GT: "America/Guatemala",
+    GU: "Pacific/Guam",
+    GW: "Africa/Bissau",
+    GY: "America/Guyana",
+    HK: "Asia/Hong_Kong",
+    HN: "America/Tegucigalpa",
+    HR: "Europe/Zagreb",
+    HT: "America/Port-au-Prince",
+    HU: "Europe/Budapest",
+    ID: "Asia/Jakarta",
+    IE: "Europe/Dublin",
+    IL: "Asia/Jerusalem",
+    IM: "Europe/Isle_of_Man",
+    IN: "Asia/Kolkata",
+    IO: "Indian/Chagos",
+    IQ: "Asia/Baghdad",
+    IR: "Asia/Tehran",
+    IS: "Atlantic/Reykjavik",
+    IT: "Europe/Rome",
+    JE: "Europe/Jersey",
+    JM: "America/Jamaica",
+    JO: "Asia/Amman",
+    JP: "Asia/Tokyo",
+    KE: "Africa/Nairobi",
+    KG: "Asia/Bishkek",
+    KH: "Asia/Phnom_Penh",
+    KI: "Pacific/Tarawa",
+    KM: "Indian/Comoro",
+    KN: "America/St_Kitts",
+    KP: "Asia/Pyongyang",
+    KR: "Asia/Seoul",
+    KW: "Asia/Kuwait",
+    KY: "America/Cayman",
+    KZ: "Asia/Almaty",
+    LA: "Asia/Vientiane",
+    LB: "Asia/Beirut",
+    LC: "America/St_Lucia",
+    LI: "Europe/Vaduz",
+    LK: "Asia/Colombo",
+    LR: "Africa/Monrovia",
+    LS: "Africa/Maseru",
+    LT: "Europe/Vilnius",
+    LU: "Europe/Luxembourg",
+    LV: "Europe/Riga",
+    LY: "Africa/Tripoli",
+    MA: "Africa/Casablanca",
+    MC: "Europe/Monaco",
+    MD: "Europe/Chisinau",
+    ME: "Europe/Podgorica",
+    MF: "America/Marigot",
+    MG: "Indian/Antananarivo",
+    MH: "Pacific/Majuro",
+    MK: "Europe/Skopje",
+    ML: "Africa/Bamako",
+    MM: "Asia/Yangon",
+    MN: "Asia/Ulaanbaatar",
+    MO: "Asia/Macau",
+    MP: "Pacific/Saipan",
+    MQ: "America/Martinique",
+    MR: "Africa/Nouakchott",
+    MS: "America/Montserrat",
+    MT: "Europe/Malta",
+    MU: "Indian/Mauritius",
+    MV: "Indian/Maldives",
+    MW: "Africa/Blantyre",
+    MX: "America/Mexico_City",
+    MY: "Asia/Kuala_Lumpur",
+    MZ: "Africa/Maputo",
+    NA: "Africa/Windhoek",
+    NC: "Pacific/Noumea",
+    NE: "Africa/Niamey",
+    NF: "Pacific/Norfolk",
+    NG: "Africa/Lagos",
+    NI: "America/Managua",
+    NL: "Europe/Amsterdam",
+    NO: "Europe/Oslo",
+    NP: "Asia/Kathmandu",
+    NR: "Pacific/Nauru",
+    NU: "Pacific/Niue",
+    NZ: "Pacific/Auckland",
+    OM: "Asia/Muscat",
+    PA: "America/Panama",
+    PE: "America/Lima",
+    PF: "Pacific/Tahiti",
+    PG: "Pacific/Port_Moresby",
+    PH: "Asia/Manila",
+    PK: "Asia/Karachi",
+    PL: "Europe/Warsaw",
+    PM: "America/Miquelon",
+    PN: "Pacific/Pitcairn",
+    PR: "America/Puerto_Rico",
+    PS: "Asia/Hebron",
+    PT: "Europe/Lisbon",
+    PW: "Pacific/Palau",
+    PY: "America/Asuncion",
+    QA: "Asia/Qatar",
+    RE: "Indian/Reunion",
+    RO: "Europe/Bucharest",
+    RS: "Europe/Belgrade",
+    RU: "Europe/Moscow",
+    RW: "Africa/Kigali",
+    SA: "Asia/Riyadh",
+    SB: "Pacific/Guadalcanal",
+    SC: "Indian/Mahe",
+    SD: "Africa/Khartoum",
+    SE: "Europe/Stockholm",
+    SG: "Asia/Singapore",
+    SH: "Atlantic/St_Helena",
+    SI: "Europe/Ljubljana",
+    SJ: "Arctic/Longyearbyen",
+    SK: "Europe/Bratislava",
+    SL: "Africa/Freetown",
+    SM: "Europe/San_Marino",
+    SN: "Africa/Dakar",
+    SO: "Africa/Mogadishu",
+    SR: "America/Paramaribo",
+    SS: "Africa/Juba",
+    ST: "Africa/Sao_Tome",
+    SV: "America/El_Salvador",
+    SX: "America/Lower_Princes",
+    SY: "Asia/Damascus",
+    SZ: "Africa/Mbabane",
+    TC: "America/Grand_Turk",
+    TD: "Africa/Ndjamena",
+    TF: "Indian/Kerguelen",
+    TG: "Africa/Lome",
+    TH: "Asia/Bangkok",
+    TJ: "Asia/Dushanbe",
+    TK: "Pacific/Fakaofo",
+    TL: "Asia/Dili",
+    TM: "Asia/Ashgabat",
+    TN: "Africa/Tunis",
+    TO: "Pacific/Tongatapu",
+    TR: "Europe/Istanbul",
+    TT: "America/Port_of_Spain",
+    TV: "Pacific/Funafuti",
+    TW: "Asia/Taipei",
+    TZ: "Africa/Dar_es_Salaam",
+    UA: "Europe/Kyiv",
+    UG: "Africa/Kampala",
+    UM: "Pacific/Midway",
+    US: "America/New_York",
+    UY: "America/Montevideo",
+    UZ: "Asia/Tashkent",
+    VA: "Europe/Vatican",
+    VC: "America/St_Vincent",
+    VE: "America/Caracas",
+    VG: "America/Tortola",
+    VI: "America/St_Thomas",
+    VN: "Asia/Ho_Chi_Minh",
+    VU: "Pacific/Efate",
+    WF: "Pacific/Wallis",
+    WS: "Pacific/Apia",
+    XK: "Europe/Belgrade",
+    YE: "Asia/Aden",
+    YT: "Indian/Mayotte",
+    ZA: "Africa/Johannesburg",
+    ZM: "Africa/Lusaka",
+    ZW: "Africa/Harare",
+};
+/**
+ * The primary IANA zone for an ISO 3166-1 alpha-2 country code (any case), or
+ * null when the code is unknown or has no populated zone.
+ */
+export function linkedInCountryPrimaryTimeZone(country) {
+    if (typeof country !== "string")
+        return null;
+    return LINKEDIN_COUNTRY_PRIMARY_TIME_ZONES[country.trim().toUpperCase()] ?? null;
+}

package/node_modules/@oxygen/shared/dist/linkedin-message-deletion.d.ts

@@ -0,0 +1,2 @@
+/** LinkedIn permits revoking a sent message only during its first hour. */
+export declare function linkedInMessageDeletionWindowOpen(sentAt: string | Date | null, now?: number): boolean;

package/node_modules/@oxygen/shared/dist/linkedin-message-deletion.js

@@ -0,0 +1,5 @@
+/** LinkedIn permits revoking a sent message only during its first hour. */
+export function linkedInMessageDeletionWindowOpen(sentAt, now = Date.now()) {
+    const sent = sentAt instanceof Date ? sentAt.getTime() : sentAt ? Date.parse(sentAt) : NaN;
+    return Number.isFinite(sent) && sent <= now && now - sent < 60 * 60 * 1000;
+}

package/node_modules/@oxygen/shared/dist/linkedin-post-keywords.d.ts

@@ -0,0 +1,44 @@
+export declare const LINKEDIN_POST_KEYWORD_FIELDS: {
+    readonly all: "all_keywords";
+    readonly any: "any_keywords";
+    readonly exclude: "exclude_keywords";
+};
+/** Each "any of" keyword is one upstream search; this bounds the fan-out. */
+export declare const MAX_ANY_KEYWORDS = 5;
+export declare const MAX_ALL_KEYWORDS = 5;
+export declare const MAX_EXCLUDE_KEYWORDS = 20;
+export declare const MAX_KEYWORD_LENGTH = 100;
+export type LinkedInPostKeywordRules = {
+    /** Every one of these must appear in the post. */
+    all: string[];
+    /** At least one of these must appear in the post. */
+    any: string[];
+    /** A post containing any of these is dropped. */
+    exclude: string[];
+};
+export type LinkedInPostKeywordMatch = {
+    keep: boolean;
+    /** The "all of" and "any of" keywords found in the post, in rule order. */
+    matched: string[];
+};
+/** Trim, drop wrapping quotes and collapse inner whitespace. Case is kept for display. */
+export declare function normalizeLinkedInPostKeyword(value: string): string;
+/**
+ * Reads the three rule lists from a request (arrays, or comma-separated strings
+ * from a CLI flag). Returns null when no rule is present, so callers can keep
+ * the plain single-search path untouched.
+ */
+export declare function readLinkedInPostKeywordRules(input: Record<string, unknown>): LinkedInPostKeywordRules | null;
+/** Everything wrong with a rule set, as customer-readable sentences. Empty when valid. */
+export declare function linkedInPostKeywordRuleProblems(rules: LinkedInPostKeywordRules): string[];
+/**
+ * The keyword strings sent upstream, one search each. `search` is the caller's
+ * free-text query and leads every search; "all of" keywords follow; each "any
+ * of" keyword gets its own search. Exclusions are never sent — they are only
+ * enforced on the returned text. Empty when there is no positive keyword at all.
+ */
+export declare function linkedInPostSearchQueries(search: string | null | undefined, rules: LinkedInPostKeywordRules): string[];
+/** How many upstream searches a request fans out to (at least one). */
+export declare function linkedInPostSearchCount(input: Record<string, unknown>): number;
+/** Applies the rules to one post's text. A post with no text matches nothing positive. */
+export declare function matchLinkedInPostKeywords(text: string | null | undefined, rules: LinkedInPostKeywordRules): LinkedInPostKeywordMatch;

package/node_modules/@oxygen/shared/dist/linkedin-post-keywords.js

@@ -0,0 +1,116 @@
+// Boolean keyword rules for LinkedIn post search.
+//
+// The managed post-search endpoint takes a keyword list and documents neither
+// AND/OR semantics between entries nor any boolean syntax, so OXYGEN does not
+// rely on the provider for them. Instead:
+//
+//   - every "any of" keyword becomes its own upstream search (the "all of"
+//     keywords ride along in each one), which is what makes an OR recall-safe;
+//   - the rules are then enforced here, on the returned post text, which is
+//     what makes them exact: case-insensitive, whitespace-normalized substring
+//     matching, the same way a person scanning the post would read it.
+//
+// The provider caps searches per hour for the whole account, so the number of
+// upstream searches one request may fan out to is bounded by MAX_ANY_KEYWORDS.
+// Pure and dependency-free: the provider adapter, the pricing resolver, the
+// signal planner and the web filter rail all read the same rules.
+export const LINKEDIN_POST_KEYWORD_FIELDS = {
+    all: "all_keywords",
+    any: "any_keywords",
+    exclude: "exclude_keywords",
+};
+/** Each "any of" keyword is one upstream search; this bounds the fan-out. */
+export const MAX_ANY_KEYWORDS = 5;
+export const MAX_ALL_KEYWORDS = 5;
+export const MAX_EXCLUDE_KEYWORDS = 20;
+export const MAX_KEYWORD_LENGTH = 100;
+/** Trim, drop wrapping quotes and collapse inner whitespace. Case is kept for display. */
+export function normalizeLinkedInPostKeyword(value) {
+    return value.trim().replace(/^["'“”‘’]+|["'“”‘’]+$/g, "").replace(/\s+/g, " ").trim();
+}
+// A hyphen or dash reads as a space: LinkedIn's own search matches "founder led
+// sales" to posts that say "founder-led sales", and on 2026-09-24 all 25 posts it
+// returned for that keyword were dropped here for the hyphen alone.
+function comparable(value) {
+    return value.toLowerCase().replace(/[-\u2010-\u2015]/g, " ").replace(/\s+/g, " ");
+}
+function readTerms(value) {
+    if (value === undefined || value === null || value === "")
+        return [];
+    const raw = Array.isArray(value) ? value.map((entry) => String(entry)) : String(value).split(",");
+    const seen = new Set();
+    const terms = [];
+    for (const entry of raw) {
+        const term = normalizeLinkedInPostKeyword(entry);
+        if (!term)
+            continue;
+        const key = comparable(term);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        terms.push(term);
+    }
+    return terms;
+}
+/**
+ * Reads the three rule lists from a request (arrays, or comma-separated strings
+ * from a CLI flag). Returns null when no rule is present, so callers can keep
+ * the plain single-search path untouched.
+ */
+export function readLinkedInPostKeywordRules(input) {
+    const rules = {
+        all: readTerms(input[LINKEDIN_POST_KEYWORD_FIELDS.all]),
+        any: readTerms(input[LINKEDIN_POST_KEYWORD_FIELDS.any]),
+        exclude: readTerms(input[LINKEDIN_POST_KEYWORD_FIELDS.exclude]),
+    };
+    return rules.all.length + rules.any.length + rules.exclude.length > 0 ? rules : null;
+}
+/** Everything wrong with a rule set, as customer-readable sentences. Empty when valid. */
+export function linkedInPostKeywordRuleProblems(rules) {
+    const problems = [];
+    if (rules.any.length > MAX_ANY_KEYWORDS) {
+        problems.push(`any_keywords takes at most ${MAX_ANY_KEYWORDS} keywords; each one is a separate LinkedIn search.`);
+    }
+    if (rules.all.length > MAX_ALL_KEYWORDS)
+        problems.push(`all_keywords takes at most ${MAX_ALL_KEYWORDS} keywords.`);
+    if (rules.exclude.length > MAX_EXCLUDE_KEYWORDS)
+        problems.push(`exclude_keywords takes at most ${MAX_EXCLUDE_KEYWORDS} keywords.`);
+    const long = [...rules.all, ...rules.any, ...rules.exclude].find((term) => term.length > MAX_KEYWORD_LENGTH);
+    if (long)
+        problems.push(`Keywords must be at most ${MAX_KEYWORD_LENGTH} characters.`);
+    const excluded = new Set(rules.exclude.map(comparable));
+    const conflict = [...rules.all, ...rules.any].find((term) => excluded.has(comparable(term)));
+    if (conflict)
+        problems.push(`"${conflict}" is both required and excluded.`);
+    return problems;
+}
+/**
+ * The keyword strings sent upstream, one search each. `search` is the caller's
+ * free-text query and leads every search; "all of" keywords follow; each "any
+ * of" keyword gets its own search. Exclusions are never sent — they are only
+ * enforced on the returned text. Empty when there is no positive keyword at all.
+ */
+export function linkedInPostSearchQueries(search, rules) {
+    const base = [search?.trim() ?? "", ...rules.all].filter(Boolean);
+    if (rules.any.length === 0)
+        return base.length > 0 ? [base.join(" ")] : [];
+    return rules.any.map((term) => [...base, term].join(" "));
+}
+/** How many upstream searches a request fans out to (at least one). */
+export function linkedInPostSearchCount(input) {
+    const rules = readLinkedInPostKeywordRules(input);
+    if (!rules)
+        return 1;
+    return Math.max(1, Math.min(MAX_ANY_KEYWORDS, rules.any.length));
+}
+/** Applies the rules to one post's text. A post with no text matches nothing positive. */
+export function matchLinkedInPostKeywords(text, rules) {
+    const body = comparable(text ?? "");
+    const has = (term) => body.includes(comparable(term));
+    const matchedAll = rules.all.filter(has);
+    const matchedAny = rules.any.filter(has);
+    const keep = matchedAll.length === rules.all.length
+        && (rules.any.length === 0 || matchedAny.length > 0)
+        && !rules.exclude.some(has);
+    return { keep, matched: [...matchedAll, ...matchedAny] };
+}

package/node_modules/@oxygen/shared/dist/linkedin-sequences.d.ts

@@ -151,4 +151,100 @@ export declare function waitStepDelayMs(step: LinkedInWaitStep): number;
  * seed is derived.
  */
 export declare function renderLinkedInTemplate(template: string, values: Record<string, unknown>, options?: RenderTemplateOptions): string;
+/**
+ * LinkedIn's connection-note ceiling for a PREMIUM sending account.
+ *
+ * Basic accounts are capped lower — see {@link LINKEDIN_INVITE_NOTE_LIMIT_BASIC}.
+ * One constant, three consumers (the definition validator, the launch copy
+ * preflight and the dispatcher); they carried three independent `300`s before.
+ */
+export declare const LINKEDIN_INVITE_NOTE_LIMIT = 300;
+/**
+ * The ceiling that actually holds for a sending account whose tier we do not
+ * know, which today is every account: nothing in `sender_accounts.metadata`
+ * records a LinkedIn Premium signal.
+ *
+ * Measured on production (2026-09-20, one tenant, 30 days). Two senders, same
+ * tenant, same table:
+ *
+ *   eca988d5   notes > 200 chars:  74 sent,   1 failed,   0 length refusals
+ *   d44fe895   notes > 200 chars:   0 sent, 138 failed, 138 length refusals
+ *
+ * d44fe895 has never delivered a single noted invite over 200 characters, and
+ * the length refusal never fires below 200 on either account. Sequence f729fc2c
+ * rendered 205–238 character notes onto that sender and destroyed 138 leads at a
+ * 100% invite failure rate, because a validator that only knows the Premium
+ * ceiling let every one of them through.
+ *
+ * 200 is safe on any tier, so it is the default and the account may only be
+ * relaxed upward from evidence.
+ */
+export declare const LINKEDIN_INVITE_NOTE_LIMIT_BASIC = 200;
+/**
+ * What a LinkedIn refusal is actually ABOUT — the question the HTTP status band
+ * cannot answer.
+ *
+ * Measured on production (2026-09-21, 14 days, one tenant), a single 403 covered
+ * a sender-side allowance, an unreadable profile and a step sent to a
+ * non-connection, and all three terminated the lead as a recipient bounce. The
+ * provider's own sentence separates them; the status never could.
+ */
+export type LinkedInRefusalScope = 
+/** Our request was malformed for this account. Ours to fix; the lead is fine. */
+"oxygen_request_invalid"
+/** We could not READ the lead's profile. Not a verdict on a send. */
+ | "profile_unreadable"
+/** This sender has exhausted a LinkedIn allowance. Nothing to do with the lead. */
+ | "sender_allowance"
+/** The step needs a connection this lead has not accepted. Ours to sequence. */
+ | "relationship_required"
+/** An invite already exists for this lead. The journey is effectively running. */
+ | "already_engaged"
+/** Unrecognised. Callers MUST preserve their existing behaviour. */
+ | "unknown";
+/**
+ * Classify a LinkedIn refusal from the provider's own account of it.
+ *
+ * Deliberately a CLOSED set of anchored, full-string matches, in the same
+ * discipline as the sequence-recovery allowlists: matching vendor prose is
+ * fragile, so an unrecognised message must degrade to `unknown` and leave the
+ * caller's behaviour exactly as it was. Extending the set is an evidence-driven
+ * act — callers log what they could not classify.
+ *
+ * Pure and total; never throws.
+ */
+export declare function classifyLinkedInRefusal(input: {
+    providerType: string | null;
+    providerMessage: string | null;
+    status: number | null;
+    operation: string | null;
+}): LinkedInRefusalScope;
+/**
+ * Does this refusal scope say the LEAD is unreachable?
+ *
+ * Only `already_engaged` is genuinely about the lead, and even that one means
+ * "an invite exists", not "this person is dead". Everything else is about our
+ * request, our sender or our sequencing, and must never brand the lead.
+ */
+export declare function linkedInRefusalBlamesLead(scope: LinkedInRefusalScope): boolean;
+/**
+ * Trim a rendered connection note to a LinkedIn account's ceiling, at a word
+ * boundary.
+ *
+ * Counts CODE POINTS, matching the launch copy preflight exactly — `.length`
+ * would count an emoji or a ZWJ sequence as two or more and the two surfaces
+ * would then disagree about the same note.
+ *
+ * Cuts at the last whitespace inside the limit so the note never ends mid-word;
+ * a single unbroken run longer than the limit has no boundary to find and is cut
+ * hard, which is the only case where that can happen.
+ *
+ * Returns the note unchanged (and `truncated: false`) when it already fits, so
+ * callers can record the trim only when there was one.
+ */
+export declare function truncateLinkedInInviteNote(note: string, limit: number): {
+    note: string;
+    truncated: boolean;
+    originalLength: number;
+};
 export {};

package/node_modules/@oxygen/shared/dist/linkedin-sequences.js

@@ -73,3 +73,126 @@ export function waitStepDelayMs(step) {
 export function renderLinkedInTemplate(template, values, options) {
     return renderTemplate(template, values, options);
 }
+/**
+ * LinkedIn's connection-note ceiling for a PREMIUM sending account.
+ *
+ * Basic accounts are capped lower — see {@link LINKEDIN_INVITE_NOTE_LIMIT_BASIC}.
+ * One constant, three consumers (the definition validator, the launch copy
+ * preflight and the dispatcher); they carried three independent `300`s before.
+ */
+export const LINKEDIN_INVITE_NOTE_LIMIT = 300;
+/**
+ * The ceiling that actually holds for a sending account whose tier we do not
+ * know, which today is every account: nothing in `sender_accounts.metadata`
+ * records a LinkedIn Premium signal.
+ *
+ * Measured on production (2026-09-20, one tenant, 30 days). Two senders, same
+ * tenant, same table:
+ *
+ *   eca988d5   notes > 200 chars:  74 sent,   1 failed,   0 length refusals
+ *   d44fe895   notes > 200 chars:   0 sent, 138 failed, 138 length refusals
+ *
+ * d44fe895 has never delivered a single noted invite over 200 characters, and
+ * the length refusal never fires below 200 on either account. Sequence f729fc2c
+ * rendered 205–238 character notes onto that sender and destroyed 138 leads at a
+ * 100% invite failure rate, because a validator that only knows the Premium
+ * ceiling let every one of them through.
+ *
+ * 200 is safe on any tier, so it is the default and the account may only be
+ * relaxed upward from evidence.
+ */
+export const LINKEDIN_INVITE_NOTE_LIMIT_BASIC = 200;
+/**
+ * Classify a LinkedIn refusal from the provider's own account of it.
+ *
+ * Deliberately a CLOSED set of anchored, full-string matches, in the same
+ * discipline as the sequence-recovery allowlists: matching vendor prose is
+ * fragile, so an unrecognised message must degrade to `unknown` and leave the
+ * caller's behaviour exactly as it was. Extending the set is an evidence-driven
+ * act — callers log what they could not classify.
+ *
+ * Pure and total; never throws.
+ */
+export function classifyLinkedInRefusal(input) {
+    const message = typeof input.providerMessage === "string" ? input.providerMessage.trim() : "";
+    if (message.length === 0)
+        return "unknown";
+    // Our invite note is longer than THIS account's ceiling. The 164 rows this
+    // matched in 14 days are leads we broke, filed as dead recipients.
+    if (input.status === 400
+        && input.providerType === "provider/invalid_parameters"
+        && /^Invalid parameters: You have reached the maximum number of characters for the custom message\.$/u.test(message)) {
+        return "oxygen_request_invalid";
+    }
+    // The profile READ failed. 121 of 318 failures in 14 days were this, on
+    // `users_get` — the lookup that runs BEFORE the invite or message, so LinkedIn
+    // never saw a send at all. It can be a genuinely unreachable profile or this
+    // sender's own profile-view allowance, and the message cannot tell them apart,
+    // which is exactly why it must not terminate the lead on the first attempt.
+    if (input.status === 403
+        && input.operation === "users_get"
+        && /^Insufficient permissions: This profile can't be accessed$/u.test(message)) {
+        return "profile_unreadable";
+    }
+    if (input.status === 403
+        && input.providerType === "provider/access_restricted"
+        && /^Access restricted: You have reached the limit for custom messages\.$/u.test(message)) {
+        return "sender_allowance";
+    }
+    if (input.status === 403
+        && input.providerType === "provider/access_restricted"
+        && /^Access restricted: This user is not a relation\.$/u.test(message)) {
+        return "relationship_required";
+    }
+    if (input.status === 422
+        && input.providerType === "provider/unprocessable_entity"
+        && /^Unprocessable entity: This user has already handled a request from you in the past 3 weeks\./u.test(message)) {
+        return "already_engaged";
+    }
+    if (input.status === 409
+        && input.providerType === "provider/conflict"
+        && /^Conflict: A relation request has already been sent to this user\.$/u.test(message)) {
+        return "already_engaged";
+    }
+    return "unknown";
+}
+/**
+ * Does this refusal scope say the LEAD is unreachable?
+ *
+ * Only `already_engaged` is genuinely about the lead, and even that one means
+ * "an invite exists", not "this person is dead". Everything else is about our
+ * request, our sender or our sequencing, and must never brand the lead.
+ */
+export function linkedInRefusalBlamesLead(scope) {
+    return scope === "already_engaged";
+}
+/**
+ * Trim a rendered connection note to a LinkedIn account's ceiling, at a word
+ * boundary.
+ *
+ * Counts CODE POINTS, matching the launch copy preflight exactly — `.length`
+ * would count an emoji or a ZWJ sequence as two or more and the two surfaces
+ * would then disagree about the same note.
+ *
+ * Cuts at the last whitespace inside the limit so the note never ends mid-word;
+ * a single unbroken run longer than the limit has no boundary to find and is cut
+ * hard, which is the only case where that can happen.
+ *
+ * Returns the note unchanged (and `truncated: false`) when it already fits, so
+ * callers can record the trim only when there was one.
+ */
+export function truncateLinkedInInviteNote(note, limit) {
+    const points = [...note];
+    const originalLength = points.length;
+    if (limit <= 0 || originalLength <= limit) {
+        return { note, truncated: false, originalLength };
+    }
+    const head = points.slice(0, limit);
+    let cut = head.length;
+    while (cut > 0 && !/\s/u.test(head[cut - 1]))
+        cut -= 1;
+    // No whitespace inside the window: one unbroken run, so a hard cut is the
+    // only option left.
+    const kept = cut === 0 ? head : head.slice(0, cut);
+    return { note: kept.join("").trimEnd(), truncated: true, originalLength };
+}