@recursiv/sdk 0.7.82 → 0.7.83

package/README.md

@@ -75,7 +75,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.agents` | `create`, `update`, `chat`, `chatStream`, `retryChatStream`, `grantProjectAccess`, `conversations`, `discover` (the app's agent directory: server search and sort, keyless-readable) |
-| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`, `requestStart` and `cancelStartRequest` (ask the other person to encrypt a chat when they have no device yet: a message with `metadata.kind` `e2ee_start_request`; the live ones are `ConversationDetail.encryption_requests`); device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
+| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `peerChanges` (contacts whose main device a reset replaced since a time), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent` (`trust_change: true`: after a contact's reset, 409 `peer_not_joined` until this account added their new device), `events`, `acknowledge`, `conversations`, `requestStart` and `cancelStartRequest` (ask the other person to encrypt a chat when they have no device yet: a message with `metadata.kind` `e2ee_start_request`; the live ones are `ConversationDetail.encryption_requests`); device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`, a contact's reset on `onE2eePeer`) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -121,6 +121,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.moderation` | Moderation actions: `publicLog`, `mine`, `appeal`; staff `apply`, `resolveAppeal`, `list({ target_type?, target_id? })` (one target's recorded actions, newest first, at most 100; none named = the network's latest; 0.7.74) and `reverse(actionId)` (sent once: a repeat answers 404 `action_not_found`; 0.7.74); agent grants `listAgentGrants`, `grantAgent`, `revokeAgent` |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
+| `r.linkPreview` | `get(url)` — a public link's Open Graph card (`data: null` when it has none). For a chat link pass `{ messageId }` or `{ conversationId }` on a signed-in key with `chat:read`: the link is fetched only when it is in the named message and a person wrote that message, or the caller wrote it in that conversation, else `refused: 'ai_link'`. A source with no id rejects (`ValidationError`). Not in encrypted chats: the server cannot read them, so leave `source` out there and apply the app's own rule |
 | `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef?, replies?: 'none' })` (`replies: 'none'`, 0.7.78: the post alone for a card, with `repliesStatus: 'not_requested'`; `getPublicConversation` and `getConnectedSocialConversation` take it too). Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id; a story a World Today story seeded carries `volume`, the first page of the posts that story counts across Minds and the open networks, whose `cursor` goes on with `curator.storyPosts` or `curator.memberStoryPosts`), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); the Viral read (fastest-moving posts across Bluesky, the Fediverse, Nostr and Minds, each against its own network's pace; 0.7.59): `getPublicViral({ network?, category?, media?: 'video', limit?: 5 | 10 | 20 | 40, cursor?, compass? })` under the member's key and keyless `getSharedViral(projectId, params)` (visitors: `compass` `all` or `hide` only; a visitor's `media: 'video'` read can carry items whose video the server withheld, so filter with the exported `viralItemHasVideo` before a video player; `item.post` narrows on `item.protocol`). `status: 'off'` resolves with no items until the app enables the read, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401 and 403, so a session failure is never read as off; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
@@ -360,6 +361,48 @@ export async function POST(req: NextRequest) {
 
 Server-side only — the `server-only` guard fails the build if it's ever imported into a client component. Keep it out of `middleware.ts` as well (edge bundle size); gate routes with a plain cookie-presence check on a shared constant.
 
+## Assistant subjects (`@recursiv/sdk/assistant`)
+
+Two pure functions for asking an assistant about a post: no network, clock, randomness or Node-only API, so a server, a React Native phone and a web app build the same model input from the same data (unreleased).
+
+```typescript
+import { buildSubjectBundle, renderBundleForModel } from '@recursiv/sdk/assistant'
+
+const { bundle, refused, excluded } = buildSubjectBundle({
+  mode: 'standard',                       // or 'sealed'
+  asker: { id: me.id, blocked_ids, muted_ids }, // a server also passes blocked_by_ids
+  post, parent, quoted, replies,          // data you already hold; nothing is fetched
+})
+if (!bundle) return showUnavailable()     // make no model call; never show the asker `audit`
+// boundary: fresh per call, e.g. 32 hex digits from crypto.getRandomValues
+const { system, user, references } = renderBundleForModel(bundle, 'explain', { boundary })
+```
+
+- `buildSubjectBundle` leaves out posts and replies whose authors turned asks off (`ai_ask_allowed`: `'all'`, `'sealed_only'` read only in Sealed, `'off'`), authors the asker blocked or muted and authors who blocked the asker, known-minor authors (unless the asker is the author), posts under a child-safety hold and posts a moderator suppressed. Pictures go as alt text and the stored caption only, never bytes or addresses. Hidden text (zero-width, bidi and tag characters, HTML comments and hidden elements, invisible markdown) is stripped, and the top 20 replies and every field are capped. Every safety flag fails closed, and an id list it cannot read throws.
+- `known_minor`, `child_safety_hold`, `assistant_suppressed`, media `held` and `blocked_by_ids` are server-side inputs: never send them to another member's client. A client builder passes each post's `assist_readable` (`'all'`, `'sealed_only'`, `'none'`), the server's verdict for that viewer, which does not say why.
+- `refused` and `excluded` are what the asker may be told: blocks, minors, holds and suppression all read `'unavailable'`, so they never say who blocked the asker, whose account is a minor's or that a post is held. `audit` holds the detail for the server's log only.
+- `renderBundleForModel(bundle, intent, { boundary, language? })` spotlights the bundle for `explain`, `summarise`, `fact_context`, `translate` or `describe`: the content sits between two lines carrying your per-call random boundary, every member-written line starts with `| `, each item is labelled with its id and handle, and `references` lists the only ids, handles and addresses an answer may use (never a picture address; write them only as plain links, never render an image the model wrote). Render only bundles built from your own reads.
+
+
+### Fixed election and crisis cards
+
+Before a model answers, check the member's own words for a fixed card. Pure, no model call, the same card on a server and a phone (unreleased):
+
+```typescript
+import { fixedCardAnswer, matchFixedCard } from '@recursiv/sdk/assistant'
+
+const match = matchFixedCard(question, { country: 'US', locale: 'en-US' }) // country: ISO 3166-1 alpha-2, if known
+if (match) {
+  show(match.card)                                  // { kind, id, title, lines, phones, links, as_of }
+  if (fixedCardAnswer(match.kind, Date.now()) === 'card_only') return // election before 2026-11-04T12:00Z: no model call
+}
+```
+
+- `crisis`: self-harm or suicide risk (first person, plans, means, worry about someone else) or immediate danger. The card gives the country's crisis line and emergency number, or the generic card (the US line, labelled, and findahelpline.com). Danger from someone else, or a medical emergency, leads with the emergency number (the police first where that is a separate number, as in Brazil, Chile and Peru: id `crisis.XX.danger`); worry about someone else gets a line addressed to the helper (`crisis.XX.other`). It always shows first; the turn may go on.
+- Matching runs in time linear in the message. Past 20,000 characters (after invisible ones are dropped), the start and the end are read.
+- `election`: only clear logistics (how, where or when to vote, registering, deadlines, polling places, mail or absentee ballots, voter ID, checking registration or a ballot). Never candidates, results, polls, fraud claims or votes on a post or poll. The US card points to vote.gov and CanIVote.org and the state election office; elsewhere the country's election authority, or a generic line.
+- English and Spanish. Every number and address has a cited source and an `as_of` date (`CRISIS_LINES`, `ELECTION_SITES`); a country with no checked entry gets the generic card, never a guessed number. `fixedCardFor(kind, options)` gives a card without a message.
+
 ## Error handling
 
 ```typescript

package/dist/assistant/fixedCardData.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The numbers and addresses the fixed election and crisis cards show (George plan G6b, risks 3 and 22). Every one was
+ * checked against the source cited beside it on FIXED_CARD_DATA_AS_OF; nothing here is filled in from memory, and a
+ * country with no checked entry gets the generic card, never a guessed number or address.
+ *
+ * Crisis lines come from findahelpline.com (ThroughLine's maintained directory, the per-country source the plan
+ * names) and, where the service publishes its own page, from that page too. Emergency numbers are findahelpline.com's
+ * per-country `emergencyNumber`; where that reaches an ambulance alone, the police number is added from a government
+ * page. Election sites are each country's own election authority, or the government's page that points to it.
+ *
+ * To change an entry: check it at its source, update `sources`, the comment above the entry and
+ * FIXED_CARD_DATA_AS_OF, and keep the contract test passing (it holds every number and address to the comment above
+ * its entry). Plain, frozen data only, so a phone and the server show the same card.
+ */
+/** The day every number and address below was last checked against its sources. */
+export declare const FIXED_CARD_DATA_AS_OF = "2026-10-08";
+/** Words in each card language. */
+export interface LocalizedText {
+    readonly en: string;
+    readonly es: string;
+}
+export interface CrisisLineData {
+    /** The service's own name, shown as written. */
+    readonly name: string;
+    /** The number as the service writes it. */
+    readonly number: string;
+    /** What a phone dials: digits, keeping a leading `*` (Chile's *4141). */
+    readonly dial: string;
+    /** The number to text, when the service takes texts; null when it is calls only. */
+    readonly text: string | null;
+    /** Open every hour of every day. Every line chosen below is. */
+    readonly always_open: boolean;
+    /** What to do after dialling, in each card language, when the service needs it (Peru's option 5). */
+    readonly after_dialling: LocalizedText | null;
+    /** One more line for a card in that language only (the 988 Lifeline's Spanish service). */
+    readonly extra_line: Partial<LocalizedText> | null;
+    /** Where `number`, `text` and `always_open` were checked. */
+    readonly sources: readonly string[];
+}
+/** One emergency number and where it was checked. */
+export interface EmergencyNumberData {
+    readonly number: string;
+    readonly sources: readonly string[];
+}
+export interface CrisisCountryData {
+    readonly name: LocalizedText;
+    /** The first line is the one the card leads with. */
+    readonly lines: readonly CrisisLineData[];
+    /**
+     * findahelpline.com's emergency number for the country: one that reaches every service, or, where `police` is set,
+     * the ambulance alone.
+     */
+    readonly emergency: string;
+    readonly emergency_sources: readonly string[];
+    /**
+     * Set only where `emergency` reaches an ambulance alone (Brazil's SAMU, Chile's 131, Peru's SAMU): the police
+     * number, which a card about danger from someone else leads with. A card always shows both.
+     */
+    readonly police?: EmergencyNumberData;
+}
+/**
+ * Per-country crisis lines, keyed by ISO 3166-1 alpha-2 code. Each line is free and open all day, every day, by its
+ * source. Kept to countries where that could be checked. The comment above each entry names every number in it and
+ * where it was checked; the contract test holds each number to its comment.
+ */
+export declare const CRISIS_LINES: Readonly<Record<string, CrisisCountryData>>;
+/** The directory the generic crisis card points to when the member's country is unknown or has no entry above. */
+export declare const CRISIS_DIRECTORY: {
+    readonly name: "findahelpline.com";
+    readonly url: "https://findahelpline.com";
+    readonly sources: readonly ["https://findahelpline.com"];
+};
+export interface ElectionSiteData {
+    /** Who runs it, as they name themselves. */
+    readonly name: string;
+    readonly url: string;
+    /** Where the address was checked. */
+    readonly sources: readonly string[];
+}
+export interface ElectionCountryData {
+    readonly name: LocalizedText;
+    readonly sites: readonly ElectionSiteData[];
+}
+/**
+ * Official election sites, keyed by ISO 3166-1 alpha-2 code: each country's national election authority, or the
+ * government page for voters. A country not listed gets the generic line, never a guessed address. Some of these
+ * hosts refuse scripted requests (403), so they were checked by hand on the date above.
+ */
+export declare const ELECTION_SITES: Readonly<Record<string, ElectionCountryData>>;
+/** Common names for a country that are not its ISO 3166-1 alpha-2 code. */
+export declare const COUNTRY_ALIASES: Readonly<Record<string, string>>;

package/dist/assistant/fixedCardData.js

@@ -0,0 +1,372 @@
+/**
+ * The numbers and addresses the fixed election and crisis cards show (George plan G6b, risks 3 and 22). Every one was
+ * checked against the source cited beside it on FIXED_CARD_DATA_AS_OF; nothing here is filled in from memory, and a
+ * country with no checked entry gets the generic card, never a guessed number or address.
+ *
+ * Crisis lines come from findahelpline.com (ThroughLine's maintained directory, the per-country source the plan
+ * names) and, where the service publishes its own page, from that page too. Emergency numbers are findahelpline.com's
+ * per-country `emergencyNumber`; where that reaches an ambulance alone, the police number is added from a government
+ * page. Election sites are each country's own election authority, or the government's page that points to it.
+ *
+ * To change an entry: check it at its source, update `sources`, the comment above the entry and
+ * FIXED_CARD_DATA_AS_OF, and keep the contract test passing (it holds every number and address to the comment above
+ * its entry). Plain, frozen data only, so a phone and the server show the same card.
+ */
+/** The day every number and address below was last checked against its sources. */
+export const FIXED_CARD_DATA_AS_OF = '2026-10-08';
+/** Freezes plain data all the way down, so no importer can change what a later card shows. Hermes-safe. */
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value))
+            deepFreeze(value[key]);
+    }
+    return value;
+}
+const FIND_A_HELPLINE = (country) => `https://findahelpline.com/countries/${country}`;
+/**
+ * Per-country crisis lines, keyed by ISO 3166-1 alpha-2 code. Each line is free and open all day, every day, by its
+ * source. Kept to countries where that could be checked. The comment above each entry names every number in it and
+ * where it was checked; the contract test holds each number to its comment.
+ */
+export const CRISIS_LINES = deepFreeze({
+    // US: 988 Suicide & Crisis Lifeline, call or text 988. Spanish: press 2 on a call, or text AYUDA to 988.
+    // Source: https://988lifeline.org, its FAQ on other languages,
+    // https://988lifeline.org/faq/calling-the-988-lifeline/faq-is-the-988-lifeline-available-in-other-languages-for-non-english-speakers/
+    // and findahelpline.com/countries/us. Emergency: 911, per findahelpline.com/countries/us.
+    US: {
+        name: { en: 'the US', es: 'EE. UU.' },
+        lines: [{
+                name: '988 Suicide & Crisis Lifeline', number: '988', dial: '988', text: '988', always_open: true,
+                after_dialling: null,
+                extra_line: { es: 'Para hablar en español, llama al 988 y oprime 2, o envía AYUDA por mensaje de texto al 988.' },
+                sources: [
+                    'https://988lifeline.org',
+                    'https://988lifeline.org/faq/calling-the-988-lifeline/faq-is-the-988-lifeline-available-in-other-languages-for-non-english-speakers/',
+                    FIND_A_HELPLINE('us'),
+                ],
+            }],
+        emergency: '911',
+        emergency_sources: [FIND_A_HELPLINE('us')],
+    },
+    // Canada: 9-8-8 Suicide Crisis Helpline, call or text 988, 24/7. Source: https://988.ca; findahelpline.com/countries/ca.
+    // Emergency: 911, per findahelpline.com/countries/ca.
+    CA: {
+        name: { en: 'Canada', es: 'Canadá' },
+        lines: [{
+                name: '9-8-8 Suicide Crisis Helpline', number: '9-8-8', dial: '988', text: '988', always_open: true,
+                after_dialling: null, extra_line: null,
+                sources: ['https://988.ca', FIND_A_HELPLINE('ca')],
+            }],
+        emergency: '911',
+        emergency_sources: [FIND_A_HELPLINE('ca')],
+    },
+    // UK: Samaritans, 116 123, free, 24/7. Source: https://www.samaritans.org/how-we-can-help/contact-samaritan/;
+    // findahelpline.com/countries/gb. Emergency: 999, per findahelpline.com/countries/gb.
+    GB: {
+        name: { en: 'the UK', es: 'el Reino Unido' },
+        lines: [{
+                name: 'Samaritans', number: '116 123', dial: '116123', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://www.samaritans.org/how-we-can-help/contact-samaritan/', FIND_A_HELPLINE('gb')],
+            }],
+        emergency: '999',
+        emergency_sources: [FIND_A_HELPLINE('gb')],
+    },
+    // Ireland: Samaritans Ireland, 116 123, 24/7. Source: https://www.samaritans.org/samaritans-ireland/;
+    // findahelpline.com/countries/ie. Emergency: 112, per findahelpline.com/countries/ie.
+    IE: {
+        name: { en: 'Ireland', es: 'Irlanda' },
+        lines: [{
+                name: 'Samaritans', number: '116 123', dial: '116123', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://www.samaritans.org/samaritans-ireland/', FIND_A_HELPLINE('ie')],
+            }],
+        emergency: '112',
+        emergency_sources: [FIND_A_HELPLINE('ie')],
+    },
+    // Australia: Lifeline, call 13 11 14 or text 0477 13 11 14, 24/7. Source: https://www.lifeline.org.au;
+    // findahelpline.com/countries/au. Emergency: 000, per findahelpline.com/countries/au.
+    AU: {
+        name: { en: 'Australia', es: 'Australia' },
+        lines: [{
+                name: 'Lifeline', number: '13 11 14', dial: '131114', text: '0477 13 11 14', always_open: true,
+                after_dialling: null, extra_line: null,
+                sources: ['https://www.lifeline.org.au', FIND_A_HELPLINE('au')],
+            }],
+        emergency: '000',
+        emergency_sources: [FIND_A_HELPLINE('au')],
+    },
+    // New Zealand: 1737, call or text 1737, 24/7. Source: https://1737.org.nz; findahelpline.com/countries/nz.
+    // Emergency: 111, per findahelpline.com/countries/nz.
+    NZ: {
+        name: { en: 'New Zealand', es: 'Nueva Zelanda' },
+        lines: [{
+                name: '1737', number: '1737', dial: '1737', text: '1737', always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://1737.org.nz', FIND_A_HELPLINE('nz')],
+            }],
+        emergency: '111',
+        emergency_sources: [FIND_A_HELPLINE('nz')],
+    },
+    // Mexico: Línea de la Vida (CONASAMA, Secretaría de Salud), 800 911 2000, 24/7.
+    // Source: https://www.gob.mx/conasama/articulos/linea-de-la-vida-800-911-2000; findahelpline.com/countries/mx.
+    // Emergency: 911, per findahelpline.com/countries/mx.
+    MX: {
+        name: { en: 'Mexico', es: 'México' },
+        lines: [{
+                name: 'Línea de la Vida', number: '800 911 2000', dial: '8009112000', text: null, always_open: true,
+                after_dialling: null, extra_line: null,
+                sources: ['https://www.gob.mx/conasama/articulos/linea-de-la-vida-800-911-2000', FIND_A_HELPLINE('mx')],
+            }],
+        emergency: '911',
+        emergency_sources: [FIND_A_HELPLINE('mx')],
+    },
+    // Spain: Línea 024 de atención a la conducta suicida (Ministerio de Sanidad), 024, 24/7.
+    // Source: https://www.sanidad.gob.es/linea024/home.htm; findahelpline.com/countries/es.
+    // Emergency: 112, per the Línea 024 page and findahelpline.com/countries/es.
+    ES: {
+        name: { en: 'Spain', es: 'España' },
+        lines: [{
+                name: 'Línea 024', number: '024', dial: '024', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://www.sanidad.gob.es/linea024/home.htm', FIND_A_HELPLINE('es')],
+            }],
+        emergency: '112',
+        emergency_sources: ['https://www.sanidad.gob.es/linea024/home.htm', FIND_A_HELPLINE('es')],
+    },
+    // Argentina: Línea Nacional de Orientación y Apoyo en la Urgencia de Salud Mental, 0800-999-0091, 24/7, 365 days.
+    // Source: https://www.argentina.gob.ar/dispositivo-0800; findahelpline.com/countries/ar. (The Centro de Asistencia
+    // al Suicida, 0800 345 1435, is open 08:00 to midnight, so it is not the line the card leads with.)
+    // Emergency: 911, per findahelpline.com/countries/ar. No police number is added: 911 is the police line where it
+    // runs, so a danger card already leads with the police.
+    AR: {
+        name: { en: 'Argentina', es: 'Argentina' },
+        lines: [{
+                name: 'Línea de Urgencia en Salud Mental', number: '0800-999-0091', dial: '08009990091', text: null, always_open: true,
+                after_dialling: null, extra_line: null,
+                sources: ['https://www.argentina.gob.ar/dispositivo-0800', FIND_A_HELPLINE('ar')],
+            }],
+        emergency: '911',
+        emergency_sources: [FIND_A_HELPLINE('ar')],
+    },
+    // Colombia: Línea 106 Nacional de Salud Mental (Ministerio de Salud), 106, 24/7. Source: findahelpline.com/countries/co;
+    // MinSalud, Directorio Nacional de Líneas de Atención en Salud Mental (August 2025):
+    // https://www.minsalud.gov.co/sites/rid/Lists/BibliotecaDigital/RIDE/VS/PP/ET/directorio-salud-mental-prevencion-suicidio-minsalud.pdf
+    // Emergency: 123, per findahelpline.com/countries/co.
+    CO: {
+        name: { en: 'Colombia', es: 'Colombia' },
+        lines: [{
+                name: 'Línea 106', number: '106', dial: '106', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: [
+                    FIND_A_HELPLINE('co'),
+                    'https://www.minsalud.gov.co/sites/rid/Lists/BibliotecaDigital/RIDE/VS/PP/ET/directorio-salud-mental-prevencion-suicidio-minsalud.pdf',
+                ],
+            }],
+        emergency: '123',
+        emergency_sources: [FIND_A_HELPLINE('co')],
+    },
+    // Chile: *4141 Línea de Prevención del Suicidio (MINSAL), 24/7.
+    // Source: https://www.gob.cl/noticias/linea-prevencion-suicidio-4141-24-horas-atencion-balance-cifras/;
+    // findahelpline.com/countries/cl. Emergency: 131 (ambulance, SAMU), per findahelpline.com/countries/cl.
+    // Police: 133 (Carabineros), free, 24 hours, per https://www.chileatiende.gob.cl/fichas/139663-fono-emergencias-133.
+    CL: {
+        name: { en: 'Chile', es: 'Chile' },
+        lines: [{
+                name: 'Línea de Prevención del Suicidio', number: '*4141', dial: '*4141', text: null, always_open: true,
+                after_dialling: null, extra_line: null,
+                sources: ['https://www.gob.cl/noticias/linea-prevencion-suicidio-4141-24-horas-atencion-balance-cifras/', FIND_A_HELPLINE('cl')],
+            }],
+        emergency: '131',
+        emergency_sources: [FIND_A_HELPLINE('cl')],
+        police: { number: '133', sources: ['https://www.chileatiende.gob.cl/fichas/139663-fono-emergencias-133'] },
+    },
+    // Peru: Línea 113 Salud (Minsa), 113, option 5 for mental health, 24/7. Source: https://www.gob.pe/555;
+    // findahelpline.com/countries/pe ("Al marcar, selecciona la opción 5"). Emergency: 106 (ambulance, SAMU), per
+    // findahelpline.com/countries/pe. Police: 105 (Policía Nacional del Perú), per its page of emergency numbers,
+    // https://www.gob.pe/institucion/pnp/contacto-y-numeros-de-emergencias.
+    PE: {
+        name: { en: 'Peru', es: 'Perú' },
+        lines: [{
+                name: 'Línea 113 Salud', number: '113', dial: '113', text: null, always_open: true,
+                after_dialling: { en: 'choose option 5', es: 'elige la opción 5' }, extra_line: null,
+                sources: ['https://www.gob.pe/555', FIND_A_HELPLINE('pe')],
+            }],
+        emergency: '106',
+        emergency_sources: [FIND_A_HELPLINE('pe')],
+        police: { number: '105', sources: ['https://www.gob.pe/institucion/pnp/contacto-y-numeros-de-emergencias'] },
+    },
+    // Brazil: CVV (Centro de Valorização da Vida), 188, 24 hours, free. Source: https://cvv.org.br;
+    // findahelpline.com/countries/br. Emergency: 192 (ambulance, SAMU), per findahelpline.com/countries/br and the
+    // Ministério das Comunicações. Police: 190 (Polícia Militar), per the Ministério das Comunicações,
+    // https://www.gov.br/mcom/pt-br/noticias/noticias_alt/2026/setembro/emergencia-voce-sabe-para-quem-ligar-quando-precisa-de-ajuda
+    BR: {
+        name: { en: 'Brazil', es: 'Brasil' },
+        lines: [{
+                name: 'CVV', number: '188', dial: '188', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://cvv.org.br', FIND_A_HELPLINE('br')],
+            }],
+        emergency: '192',
+        emergency_sources: [
+            FIND_A_HELPLINE('br'),
+            'https://www.gov.br/mcom/pt-br/noticias/noticias_alt/2026/setembro/emergencia-voce-sabe-para-quem-ligar-quando-precisa-de-ajuda',
+        ],
+        police: {
+            number: '190',
+            sources: ['https://www.gov.br/mcom/pt-br/noticias/noticias_alt/2026/setembro/emergencia-voce-sabe-para-quem-ligar-quando-precisa-de-ajuda'],
+        },
+    },
+    // France: 3114, numéro national de prévention du suicide, 24/7. Source: https://3114.fr;
+    // findahelpline.com/countries/fr. Emergency: 112, per findahelpline.com/countries/fr.
+    FR: {
+        name: { en: 'France', es: 'Francia' },
+        lines: [{
+                name: '3114', number: '3114', dial: '3114', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://3114.fr', FIND_A_HELPLINE('fr')],
+            }],
+        emergency: '112',
+        emergency_sources: [FIND_A_HELPLINE('fr')],
+    },
+    // Germany: TelefonSeelsorge, 0800 111 0 111 (also 0800 111 0 222 and 116 123), 24/7.
+    // Source: https://www.telefonseelsorge.de; findahelpline.com/countries/de. Emergency: 112, per
+    // findahelpline.com/countries/de.
+    DE: {
+        name: { en: 'Germany', es: 'Alemania' },
+        lines: [{
+                name: 'TelefonSeelsorge', number: '0800 111 0 111', dial: '08001110111', text: null, always_open: true,
+                after_dialling: null, extra_line: null,
+                sources: ['https://www.telefonseelsorge.de', FIND_A_HELPLINE('de')],
+            }],
+        emergency: '112',
+        emergency_sources: [FIND_A_HELPLINE('de')],
+    },
+    // India: Tele MANAS (Ministry of Health and Family Welfare), 14416, 24/7. Source:
+    // https://telemanas.mohfw.gov.in/home; findahelpline.com/countries/in. Emergency: 112, per
+    // findahelpline.com/countries/in.
+    IN: {
+        name: { en: 'India', es: 'la India' },
+        lines: [{
+                name: 'Tele MANAS', number: '14416', dial: '14416', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://telemanas.mohfw.gov.in/home', FIND_A_HELPLINE('in')],
+            }],
+        emergency: '112',
+        emergency_sources: [FIND_A_HELPLINE('in')],
+    },
+    // Netherlands: 113 Zelfmoordpreventie, 113, 24/7. Source: https://www.113.nl; findahelpline.com/countries/nl.
+    // Emergency: 112, per findahelpline.com/countries/nl.
+    NL: {
+        name: { en: 'the Netherlands', es: 'los Países Bajos' },
+        lines: [{
+                name: '113 Zelfmoordpreventie', number: '113', dial: '113', text: null, always_open: true, after_dialling: null, extra_line: null,
+                sources: ['https://www.113.nl', FIND_A_HELPLINE('nl')],
+            }],
+        emergency: '112',
+        emergency_sources: [FIND_A_HELPLINE('nl')],
+    },
+});
+/** The directory the generic crisis card points to when the member's country is unknown or has no entry above. */
+export const CRISIS_DIRECTORY = deepFreeze({
+    name: 'findahelpline.com',
+    url: 'https://findahelpline.com',
+    // Source: https://findahelpline.com (ThroughLine's international helpline directory), checked 2026-10-08.
+    sources: ['https://findahelpline.com'],
+});
+/**
+ * Official election sites, keyed by ISO 3166-1 alpha-2 code: each country's national election authority, or the
+ * government page for voters. A country not listed gets the generic line, never a guessed address. Some of these
+ * hosts refuse scripted requests (403), so they were checked by hand on the date above.
+ */
+export const ELECTION_SITES = deepFreeze({
+    // US: vote.gov (U.S. government, GSA) links to every state's election office; CanIVote.org (the National
+    // Association of Secretaries of State) finds a state's site and polling place. The plan's "Find my state's site"
+    // button. Source: https://vote.gov, https://www.canivote.org (redirects to https://www.nass.org/can-I-vote).
+    US: {
+        name: { en: 'the US', es: 'EE. UU.' },
+        sites: [
+            { name: 'vote.gov', url: 'https://vote.gov', sources: ['https://vote.gov'] },
+            { name: 'CanIVote.org', url: 'https://www.canivote.org', sources: ['https://www.nass.org/can-I-vote'] },
+        ],
+    },
+    // Canada: Elections Canada (federal). Source: https://www.elections.ca.
+    CA: {
+        name: { en: 'Canada', es: 'Canadá' },
+        sites: [{ name: 'Elections Canada', url: 'https://www.elections.ca', sources: ['https://www.elections.ca'] }],
+    },
+    // UK: the Electoral Commission. Source: https://www.electoralcommission.org.uk.
+    GB: {
+        name: { en: 'the UK', es: 'el Reino Unido' },
+        sites: [{
+                name: 'Electoral Commission', url: 'https://www.electoralcommission.org.uk',
+                sources: ['https://www.electoralcommission.org.uk'],
+            }],
+    },
+    // Ireland: An Coimisiún Toghcháin, the Electoral Commission. Source: https://www.electoralcommission.ie.
+    IE: {
+        name: { en: 'Ireland', es: 'Irlanda' },
+        sites: [{ name: 'Electoral Commission', url: 'https://www.electoralcommission.ie', sources: ['https://www.electoralcommission.ie'] }],
+    },
+    // Australia: the Australian Electoral Commission. Source: https://www.aec.gov.au.
+    AU: {
+        name: { en: 'Australia', es: 'Australia' },
+        sites: [{ name: 'Australian Electoral Commission', url: 'https://www.aec.gov.au', sources: ['https://www.aec.gov.au'] }],
+    },
+    // New Zealand: the Electoral Commission (elections.org.nz redirects here). Source: https://vote.nz.
+    NZ: {
+        name: { en: 'New Zealand', es: 'Nueva Zelanda' },
+        sites: [{ name: 'Electoral Commission', url: 'https://vote.nz', sources: ['https://vote.nz', 'https://www.elections.org.nz'] }],
+    },
+    // India: the Election Commission of India. Source: https://www.eci.gov.in.
+    IN: {
+        name: { en: 'India', es: 'la India' },
+        sites: [{ name: 'Election Commission of India', url: 'https://www.eci.gov.in', sources: ['https://www.eci.gov.in'] }],
+    },
+    // Mexico: the Instituto Nacional Electoral. Source: https://www.ine.mx.
+    MX: {
+        name: { en: 'Mexico', es: 'México' },
+        sites: [{ name: 'Instituto Nacional Electoral', url: 'https://www.ine.mx', sources: ['https://www.ine.mx'] }],
+    },
+    // Brazil: the Tribunal Superior Eleitoral. Source: https://www.tse.jus.br.
+    BR: {
+        name: { en: 'Brazil', es: 'Brasil' },
+        sites: [{ name: 'Tribunal Superior Eleitoral', url: 'https://www.tse.jus.br', sources: ['https://www.tse.jus.br'] }],
+    },
+    // Spain: the INE's Oficina del Censo Electoral (the electoral roll and where to vote). Source:
+    // https://www.ine.es/oficina_censo/.
+    ES: {
+        name: { en: 'Spain', es: 'España' },
+        sites: [{
+                name: 'Oficina del Censo Electoral del INE', url: 'https://www.ine.es/oficina_censo/',
+                sources: ['https://www.ine.es/oficina_censo/'],
+            }],
+    },
+    // Argentina: the Justicia Nacional Electoral's padrón lookup (where you vote). Source: https://www.padron.gob.ar.
+    AR: {
+        name: { en: 'Argentina', es: 'Argentina' },
+        sites: [{ name: 'Justicia Nacional Electoral', url: 'https://www.padron.gob.ar', sources: ['https://www.padron.gob.ar'] }],
+    },
+    // Colombia: the Registraduría Nacional del Estado Civil. Source: https://www.registraduria.gov.co.
+    CO: {
+        name: { en: 'Colombia', es: 'Colombia' },
+        sites: [{
+                name: 'Registraduría Nacional del Estado Civil', url: 'https://www.registraduria.gov.co',
+                sources: ['https://www.registraduria.gov.co'],
+            }],
+    },
+    // Chile: the Servicio Electoral de Chile (Servel). Source: https://www.servel.cl.
+    CL: {
+        name: { en: 'Chile', es: 'Chile' },
+        sites: [{ name: 'Servicio Electoral de Chile', url: 'https://www.servel.cl', sources: ['https://www.servel.cl'] }],
+    },
+    // Germany: Die Bundeswahlleiterin (the Federal Returning Officer). Source: https://www.bundeswahlleiterin.de.
+    DE: {
+        name: { en: 'Germany', es: 'Alemania' },
+        sites: [{ name: 'Die Bundeswahlleiterin', url: 'https://www.bundeswahlleiterin.de', sources: ['https://www.bundeswahlleiterin.de'] }],
+    },
+    // France: Service-Public.fr's elections pages (the government's site for voters). Source:
+    // https://www.service-public.gouv.fr/particuliers/vosdroits/N47.
+    FR: {
+        name: { en: 'France', es: 'Francia' },
+        sites: [{
+                name: 'Service-Public.fr', url: 'https://www.service-public.gouv.fr/particuliers/vosdroits/N47',
+                sources: ['https://www.service-public.gouv.fr/particuliers/vosdroits/N47'],
+            }],
+    },
+});
+/** Common names for a country that are not its ISO 3166-1 alpha-2 code. */
+export const COUNTRY_ALIASES = deepFreeze({ UK: 'GB' });

package/dist/assistant/fixedCards.d.ts

@@ -0,0 +1,35 @@
+import type { FixedCard, FixedCardAnswer, FixedCardKind, FixedCardMatch, FixedCardOptions } from './types.js';
+/**
+ * The longest message read in full, counted after invisible characters are dropped. Past it, the first and the last
+ * FIXED_CARD_SCAN_LIMIT / 2 characters are read, each on its own, so a long paste that ends with a crisis statement
+ * still matches.
+ */
+export declare const FIXED_CARD_SCAN_LIMIT = 20000;
+/**
+ * Until this moment an election card replaces the model's answer; after it, the card shows first and the turn may go
+ * on. Noon UTC on 2026-11-04: the day after the US midterms (2026-11-03), after the last US polls close (Hawaii and
+ * the Aleutians, 05:00 to 06:00 UTC on 11-04).
+ */
+export declare const ELECTION_CARD_ONLY_UNTIL = "2026-11-04T12:00:00Z";
+/**
+ * Lower case, no accents, no apostrophes ("I'm" reads "im"), look-alike and "fancy font" letters as plain ones, digits
+ * standing for letters read as letters, and every other run of non-letters one space: what the phrase lists are
+ * written against. Past FIXED_CARD_SCAN_LIMIT characters, the first and last halves joined by a space.
+ */
+export declare function normaliseForMatching(text: string): string;
+/**
+ * The fixed card a member's message calls for, or null. Crisis wins over election when a message shows both. Pass
+ * the member's own words (their question to George), not the post or chat they are asking about.
+ */
+export declare function matchFixedCard(text: string, options?: FixedCardOptions): FixedCardMatch | null;
+/**
+ * A fixed card without reading a message: for a caller that already knows it must show one (the crisis card for a
+ * known under-18 member, D10). The language comes from `locale`, else English.
+ */
+export declare function fixedCardFor(kind: FixedCardKind, options?: FixedCardOptions): FixedCard;
+/**
+ * What the turn does after a card: a crisis card always shows first and the turn may go on to a supportive answer;
+ * an election card replaces the model's answer until ELECTION_CARD_ONLY_UNTIL. `now` is epoch milliseconds or an ISO
+ * time from the caller's clock; one that cannot be read gives 'card_only'.
+ */
+export declare function fixedCardAnswer(kind: FixedCardKind, now: number | string): FixedCardAnswer;