b2match-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 b2match-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,268 @@
-# Temporary Holding Version
+# b2match-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/barzoj/b2match-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/barzoj/b2match-mcp/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/barzoj/b2match-mcp/graph/badge.svg)](https://codecov.io/gh/barzoj/b2match-mcp)
+[![npm version](https://img.shields.io/npm/v/b2match-mcp)](https://www.npmjs.com/package/b2match-mcp)
+[![License: MIT](https://img.shields.io/npm/l/b2match-mcp)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/b2match-mcp)](https://nodejs.org/)
+
+Read-only MCP server for the [B2match](https://www.b2match.com/) event and matchmaking platform.
+
+This package is designed to be run locally by the user via `npx` and stdio MCP transport.
+
+**Disclaimer:** This project is unofficial and is not affiliated with, endorsed by, or supported by B2match. It uses B2match's undocumented web GraphQL API, so field availability can change without notice. Use it in accordance with [B2match's Terms of Service](https://www.b2match.com/) and GDPR. Participant profiles can be other people's personal data — keep exports local, respect each event's visibility rules, and do not harvest or republish personal data.
+
+## Read-only and privacy guarantees
+
+- The MCP server sends only GraphQL `query` operations. Mutations and subscriptions are parsed and rejected before any network call.
+- Known "read-looking" write operations are explicitly blocked, including profile-view, mark-as-read, session-attendance, and bookmark mutations.
+- B2match can still update its own read/seen counters when certain query fields are selected. See [Server-side side effects](#server-side-side-effects).
+- It never calls Plausible, Sentry, Google Analytics, HubSpot, LinkedIn pixel, or any non-B2match analytics endpoint.
+- It makes no external calls other than `https://api.b2match.com/v4/query` and the B2match Google login URL opened by the CLI.
+- No telemetry or analytics are collected by this package.
+- Tokens are never printed by tools or status commands.
+- Tokens are stored in the OS keychain when available, otherwise in a `0600` config file.
+
+## Install / run
+
+Requires Node.js 20 or newer. On macOS with Apple Silicon, the recommended install path is `npx`; no native build step is required for the auth storage path.
+
+```bash
+npx -y b2match-mcp
+```
+
+From a checkout:
+
+```bash
+npm install
+npm run build
+node dist/cli.js
+```
+
+## MCP client config
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "b2match": {
+      "command": "npx",
+      "args": ["-y", "b2match-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "b2match": {
+      "command": "npx",
+      "args": ["-y", "b2match-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json` or user MCP settings:
+
+```json
+{
+  "servers": {
+    "b2match": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "b2match-mcp"]
+    }
+  }
+}
+```
+
+For local development from this checkout:
+
+```json
+{
+  "mcpServers": {
+    "b2match": {
+      "command": "node",
+      "args": ["/absolute/path/to/b2match-mcp/dist/cli.js"]
+    }
+  }
+}
+```
+
+## Authentication
+
+Public event data works anonymously. Personal data such as viewer profile, active events, meetings, schedule, conversations, notifications, and availability requires a locally stored B2match session token.
+
+### macOS / Linux login
+
+```bash
+b2match-mcp login https://www.b2match.com/e/<event-slug>
+# or: npx b2match-mcp login https://www.b2match.com/e/<event-slug>
+```
+
+The default command:
+
+1. Resolves the event anonymously and asks B2match for its Google login URL.
+2. Launches your installed Chrome, Chromium, Edge, or Brave as a separate process.
+3. Uses a dedicated persistent profile under the tool config directory, not your everyday browser profile.
+4. Opens a remote-debugging port on `127.0.0.1` for that dedicated profile only (not your everyday browser). The port is closed when login finishes or times out.
+5. Lets you complete Google sign-in and 2FA by hand. The CLI does not fill any form.
+6. Waits for a JWT on the event tab URL (`www.b2match.com/e/<slug>?token=…`) or the event session cookie, validates it with a cheap viewer query, stores it, and closes that browser window. Chrome can 404 the post-Google event page before a cookie is set; the URL token is the path that works in that case.
+
+Repeat logins are usually one click because the dedicated profile keeps the Google session.
+
+macOS may show a Keychain access prompt the first time the CLI stores or reads the token. Approve access for `b2match-mcp`/your terminal if you want Keychain storage. If access is denied or Keychain is unavailable, the CLI falls back to a private config file.
+
+### Paste-only / environment token
+
+Use these only when the dedicated browser flow cannot run:
+
+```bash
+b2match-mcp login --paste
+# or: npx b2match-mcp login --paste
+B2MATCH_TOKEN='<session-cookie-value>' b2match-mcp
+```
+
+`B2MATCH_TOKEN` is used in memory and is not persisted. Do not pass tokens on the command line; that leaks them into shell history.
+
+### Status / logout
+
+```bash
+b2match-mcp status
+b2match-mcp logout
+b2match-mcp logout --all
+```
+
+`logout` removes the stored B2match token only. `logout --all` also deletes the dedicated browser profile.
+
+### Dedicated browser profile
+
+Login uses a dedicated Chromium profile at `~/.config/b2match-mcp/browser-profile` (or `$B2MATCH_MCP_CONFIG_DIR/browser-profile` / `$XDG_CONFIG_HOME/b2match-mcp/browser-profile`). That profile keeps the Google session, so a later `login` is usually one click.
+
+To wipe the Google session as well as the stored B2match token:
+
+```bash
+b2match-mcp logout --all
+```
+
+To delete only the profile and keep the stored token:
+
+```bash
+rm -rf ~/.config/b2match-mcp/browser-profile
+```
+
+`logout` without `--all` keeps the profile so the next login can reuse Google.
+
+### Storage locations
+
+- macOS: login Keychain via `/usr/bin/security` (`b2match-mcp` service, `default` account).
+- Linux: `secret-tool` / libsecret when installed and unlocked.
+- Windows: private fallback file.
+- Fallback file: `$B2MATCH_MCP_CONFIG_DIR/auth.json`, `$XDG_CONFIG_HOME/b2match-mcp/auth.json`, or `~/.config/b2match-mcp/auth.json`, written with `0600` permissions.
+- Dedicated browser profile: `~/.config/b2match-mcp/browser-profile` (same config directory).
+
+If a token is a JWT, the CLI records its `exp` claim as `expiresAt`. B2match also has opaque tokens, in which case lifetime cannot be known locally. A 401 on an authenticated viewer check is reported as invalid/expired and remembered for the process. Public tools then continue anonymously without deleting the stored token.
+
+### Troubleshooting login
+
+- **No supported browser found:** install Chrome, Chromium, Edge, or Brave, or use `b2match-mcp login --paste`.
+- **Google blocks the window:** finish sign-in in the dedicated window if possible; otherwise use `--paste`.
+- **Timeout / 404 after Google:** the CLI also reads a JWT from the event tab URL if Chrome 404s before a cookie is set. Finish sign-in and wait; or use `--paste`.
+- **Keychain prompt denied:** run `b2match-mcp logout`, then `login` again and approve the prompt; or set `B2MATCH_MCP_DISABLE_KEYCHAIN=1` to use the private file fallback.
+- **Wrong/expired token:** run `b2match-mcp logout`, sign in again, and repeat `login`.
+
+## Tools
+
+Public/anonymous:
+
+- `get_event` - event metadata, dates, registration window, login methods, and navigation. Numeric ids and slugs return the same fields.
+- `list_participants` - compact participant summaries with pagination and optional search. Set `detail=true` for the fuller list payload.
+- `get_participant` - one participant profile, without firing profile-view tracking.
+- `list_organisations`, `get_organisation` - organisation/participation pages. Menu paths such as `/components/<id>` are resolved automatically.
+- `list_opportunities`, `get_opportunity` - marketplace entries. Menu paths are resolved automatically; unknown opportunities return an MCP not-found error.
+- `get_agenda`, `get_session`, `list_session_attendees`, `list_speakers`.
+
+Authenticated:
+
+- `auth_status`
+- `list_my_events`
+- `my_participation`
+- `my_schedule`
+- `my_meetings` - meetings by status; unfiltered responses use a compact availability summary unless `detail=true`
+- `my_availability` - merged free ranges per day by default; `detail=true` for the full timeslot grid
+- `find_meeting_slots`
+- `meeting_recommendations`
+- `list_conversations` - last-message previews; does not mark conversations as read
+- `get_conversation` - disabled by default because fetching messages marks the conversation as read; see side effects
+- `list_notifications` - unread/unseen counters by default; the full list resets unseen
+
+Optional raw query:
+
+- `graphql_read` is registered only when `B2MATCH_ALLOW_RAW=1`. It still rejects non-query operations and, unless `B2MATCH_ALLOW_SIDE_EFFECT_READS=1`, queries that select `messagesV2` or the notification list.
+
+## Server-side side effects
+
+This client never sends B2match mutations such as `MarkConversationAsSeen` or `ReadNotification`. B2match can still mutate its own read/seen state when a **query** selects certain fields:
+
+- `get_conversation` (`messagesV2`) marks that conversation as read (unread-conversations count decreases).
+- `list_notifications` with the `notifications(...)` list field resets the unseen counter (unseen → 0). The unread counter is unchanged. Fetching `notificationsCounter` alone does not reset unseen.
+- `list_conversations` (including `lastMessageV2`) has no known side effects.
+
+Gating:
+
+- Default `list_notifications` returns only `unread`/`unseen` counters.
+- `get_conversation` and the full notification list require `B2MATCH_ALLOW_SIDE_EFFECT_READS=1` **and** an explicit tool argument (`acknowledge_marks_read` / `acknowledge_marks_seen`).
+- `graphql_read` rejects queries that select `messagesV2` or the `notifications` list unless the same env var is set.
+
+Use `list_conversations` when you only need the last message.
+
+Each event-scoped tool accepts a current event URL (`https://www.b2match.com/e/<slug>`), a legacy event URL (`https://<slug>.b2match.io`), a bare slug, or a numeric event id.
+
+Authenticated tools return an MCP error when no token is stored, with instructions to log in. They say the token is invalid or expired only after a stored token receives HTTP 401.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for lint, format, coverage, Conventional Commits, and the read-only guard.
+
+Live smoke test against a public event (opt-in, not run in CI):
+
+```bash
+B2MATCH_LIVE_SMOKE=1 B2MATCH_SMOKE_EVENT='https://www.b2match.com/e/<event-slug>' npm test -- tests/live-smoke.test.ts
+```
+
+The smoke test is skipped unless both environment variables are set.
+
+## Publishing
+
+Releases are cut by Release Please from Conventional Commits on `main`. The same workflow (`.github/workflows/release-please.yml`) publishes with `npm publish --provenance --access public` when a release is created. Provenance requires a public repo. Configure npm trusted publishing against `release-please.yml`. `NPM_TOKEN` is a documented fallback only. `.github/workflows/publish.yml` is a manual republish trigger. After the first 0.1.0 release, remove `"release-as": "0.1.0"` from `release-please-config.json`.
+
+## Verification status
+
+Verified in this repo:
+
+- TypeScript build and unit tests.
+- Query-only enforcement, event identifier parsing, cookie-name helpers, dedicated-browser launch args, section-path resolution, compact participant summaries, and 401/auth-error policy.
+- Packed CLI `--help` / `status`.
+- Opt-in anonymous live smoke that exercises every public tool when `B2MATCH_SMOKE_EVENT` is provided.
+
+Requires a real login on a real machine:
+
+- Dedicated-profile Google login, Keychain prompt, URL-token or cookie capture.
+- Authenticated tools: `list_my_events`, `my_participation`, schedule, meetings, availability, meeting slots, recommendations, conversations, and notifications.
+
+## License
+
+MIT.

package/dist/api.d.ts

@@ -0,0 +1,89 @@
+import { B2matchClient } from "./client.js";
+export declare class ConversationNotFoundError extends Error {
+    constructor(message?: string);
+}
+export declare class RouteNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class B2matchApi {
+    private readonly client;
+    private readonly routeTypeCache;
+    constructor(client: B2matchClient);
+    authStatus(): Promise<unknown>;
+    listMyEvents(): Promise<unknown>;
+    getEvent(event: string): Promise<import("./client.js").ResolvedEvent>;
+    myParticipation(event: string): Promise<unknown>;
+    listParticipants(event: string, options?: {
+        first?: number;
+        after?: string;
+        query?: string;
+        detail?: boolean;
+    }): Promise<{
+        event: {
+            id: string;
+            euid: string;
+            title: string | undefined;
+        };
+        totalCount: unknown;
+        pageInfo: unknown;
+        nodes: any[];
+    }>;
+    getParticipant(event: string, participantId: string): Promise<unknown>;
+    listOrganisations(event: string, options?: {
+        path?: string;
+        first?: number;
+        after?: string;
+    }): Promise<unknown>;
+    getOrganisation(event: string, participationId: string, path?: string): Promise<unknown>;
+    listOpportunities(event: string, options?: {
+        path?: string;
+        first?: number;
+        after?: string;
+    }): Promise<unknown>;
+    getOpportunity(event: string, opportunityId: string, path?: string): Promise<unknown>;
+    getAgenda(event: string, path?: string): Promise<unknown>;
+    getSession(event: string, sessionId?: string, options?: {
+        path?: string;
+        first?: number;
+        after?: string;
+    }): Promise<unknown>;
+    listSessionAttendees(event: string, sessionId?: string, options?: {
+        path?: string;
+        first?: number;
+        after?: string;
+    }): Promise<unknown>;
+    listSpeakers(event: string, options?: {
+        path?: string;
+        first?: number;
+        after?: string;
+    }): Promise<unknown>;
+    mySchedule(event: string, includePdfLink?: boolean): Promise<Record<string, unknown>>;
+    myMeetings(event: string, status?: "accepted" | "receivedInvitations" | "sentInvitations" | "canceled", detail?: boolean): Promise<Record<string, unknown>>;
+    myAvailability(event: string, detail?: boolean): Promise<{
+        availability: unknown;
+        isAvailable: unknown;
+        openNetworkingEnabled: unknown;
+    }>;
+    findMeetingSlots(event: string, participantIds: string[], options?: {
+        day?: string;
+        duration?: string;
+        isLongTermNetworking?: boolean;
+    }): Promise<unknown>;
+    meetingRecommendations(event: string): Promise<unknown>;
+    listConversations(event: string, options?: {
+        first?: number;
+        after?: string;
+    }): Promise<unknown>;
+    getConversation(conversationId: string): Promise<{
+        conversation?: unknown;
+    }>;
+    listNotifications(event: string, options?: {
+        first?: number;
+        after?: string;
+        list?: boolean;
+    }): Promise<unknown>;
+    private routeSection;
+    private routeDetail;
+    private peekRoutes;
+    private route;
+}

package/dist/api.js

@@ -0,0 +1,264 @@
+import { compactAvailability } from "./availability.js";
+import { B2matchGraphQLError } from "./client.js";
+import { DETAIL_TYPENAMES, SECTION_TYPENAMES, candidateSectionPaths, detailPathCandidates, normalizeRoutePath, opportunityDetailPaths, parseRouteTypenames, resolveSectionPath, routeTypename, sessionAttendees, unavailableSection } from "./directory.js";
+import { compactParticipant } from "./participants.js";
+import { CONVERSATION, CONVERSATIONS, DIRECTORY_ROUTE, FIND_MEETING_SLOTS, LIST_PARTICIPANTS, MY_EVENTS, MY_MEETINGS_AND_AVAILABILITY, MY_PARTICIPATION, MY_SCHEDULE, NOTIFICATION_COUNTERS, NOTIFICATIONS, PARTICIPANT_DETAIL, RECOMMENDATIONS, buildRouteTypenamesQuery, routeTypenameVariables, VIEWER_STATUS } from "./queries.js";
+import { defaultRouteVariables, pageVars } from "./tooling.js";
+export class ConversationNotFoundError extends Error {
+    constructor(message = "Conversation not found.") {
+        super(message);
+        this.name = "ConversationNotFoundError";
+    }
+}
+export class RouteNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RouteNotFoundError";
+    }
+}
+export class B2matchApi {
+    client;
+    routeTypeCache = new Map();
+    constructor(client) {
+        this.client = client;
+    }
+    async authStatus() {
+        return this.client.query(VIEWER_STATUS, {}, { requireAuth: true, cache: false });
+    }
+    async listMyEvents() {
+        return this.client.query(MY_EVENTS, {}, { requireAuth: true, cache: true });
+    }
+    async getEvent(event) {
+        return this.client.resolveEvent(event);
+    }
+    async myParticipation(event) {
+        const resolved = await this.client.resolveEvent(event);
+        return this.client.query(MY_PARTICIPATION, { euid: resolved.euid }, { requireAuth: true, cache: true });
+    }
+    async listParticipants(event, options = {}) {
+        const resolved = await this.client.resolveEvent(event);
+        const data = await this.client.query(LIST_PARTICIPANTS, {
+            eventId: resolved.id,
+            euid: resolved.euid,
+            query: options.query ?? "",
+            ...pageVars(options.first, options.after)
+        }, { cache: true });
+        const connection = (data.event?.participants ?? {});
+        const nodes = Array.isArray(connection.nodes) ? connection.nodes : [];
+        return {
+            event: { id: resolved.id, euid: resolved.euid, title: resolved.title },
+            totalCount: connection.totalCount,
+            pageInfo: connection.pageInfo,
+            nodes: options.detail ? nodes : nodes.map((node) => compactParticipant(node))
+        };
+    }
+    async getParticipant(event, participantId) {
+        const resolved = await this.client.resolveEvent(event);
+        return this.client.query(PARTICIPANT_DETAIL, { euid: resolved.euid, id: participantId }, { cache: true });
+    }
+    async listOrganisations(event, options = {}) {
+        return this.routeSection(event, "organisations", options);
+    }
+    async getOrganisation(event, participationId, path) {
+        return this.routeDetail(event, "organisations", participationId, path);
+    }
+    async listOpportunities(event, options = {}) {
+        return this.routeSection(event, "opportunities", options);
+    }
+    async getOpportunity(event, opportunityId, path) {
+        const resolved = await this.client.resolveEvent(event);
+        const expected = DETAIL_TYPENAMES.opportunities;
+        const sectionPaths = path?.trim() ? [] : candidateSectionPaths(resolved.raw, "opportunities");
+        const types = sectionPaths.length > 0
+            ? await this.peekRoutes(resolved.euid, sectionPaths)
+            : new Map();
+        const section = sectionPaths.find((candidate) => types.get(candidate) === SECTION_TYPENAMES.opportunities);
+        const candidates = opportunityDetailPaths(section, opportunityId, path);
+        let last;
+        for (const candidate of candidates) {
+            last = await this.route(resolved.euid, candidate);
+            if (routeTypename(last) === expected) {
+                return last;
+            }
+            if (path?.trim()) {
+                break;
+            }
+        }
+        throw new RouteNotFoundError("Opportunity not found.");
+    }
+    async getAgenda(event, path) {
+        return this.routeSection(event, "agenda", { path, first: 50 });
+    }
+    async getSession(event, sessionId, options = {}) {
+        if (options.path?.trim()) {
+            const resolved = await this.client.resolveEvent(event);
+            return this.route(resolved.euid, normalizeRoutePath(options.path), options.first, options.after);
+        }
+        if (!sessionId?.trim()) {
+            throw new Error("session_id is required unless path is provided.");
+        }
+        return this.routeDetail(event, "sessions", sessionId, undefined, options.first, options.after);
+    }
+    async listSessionAttendees(event, sessionId, options = {}) {
+        return sessionAttendees(await this.getSession(event, sessionId, options));
+    }
+    async listSpeakers(event, options = {}) {
+        return this.routeSection(event, "speakers", options);
+    }
+    async mySchedule(event, includePdfLink = false) {
+        const resolved = await this.client.resolveEvent(event);
+        const data = await this.client.query(MY_SCHEDULE, { euid: resolved.euid }, { requireAuth: true, cache: false });
+        if (!includePdfLink) {
+            const participant = (data.viewer?.participantByEuid ?? {});
+            delete participant.pdfAgendaUrl;
+        }
+        return data;
+    }
+    async myMeetings(event, status, detail = false) {
+        const resolved = await this.client.resolveEvent(event);
+        const data = await this.client.query(MY_MEETINGS_AND_AVAILABILITY, { euid: resolved.euid }, { requireAuth: true, cache: false });
+        const viewer = (data.viewer ?? {});
+        const participant = (viewer.participantByEuid ?? {});
+        if (status) {
+            return { [status]: participant.meetings?.[status] };
+        }
+        if (detail) {
+            return data;
+        }
+        return {
+            ...data,
+            viewer: {
+                ...viewer,
+                participantByEuid: {
+                    ...participant,
+                    availability: compactAvailability(participant.availability)
+                }
+            }
+        };
+    }
+    async myAvailability(event, detail = false) {
+        const resolved = await this.client.resolveEvent(event);
+        const data = await this.client.query(MY_MEETINGS_AND_AVAILABILITY, { euid: resolved.euid }, { requireAuth: true, cache: false });
+        const participant = (data.viewer?.participantByEuid ?? {});
+        return {
+            availability: detail ? participant.availability : compactAvailability(participant.availability),
+            isAvailable: participant.isAvailable,
+            openNetworkingEnabled: participant.openNetworkingEnabled
+        };
+    }
+    async findMeetingSlots(event, participantIds, options = {}) {
+        const resolved = await this.client.resolveEvent(event);
+        return this.client.query(FIND_MEETING_SLOTS, {
+            euid: resolved.euid,
+            participantIds,
+            day: options.day ?? "",
+            duration: options.duration ?? null,
+            meetingId: null,
+            isLtm: options.isLongTermNetworking ?? false
+        }, { requireAuth: true, cache: false });
+    }
+    async meetingRecommendations(event) {
+        const resolved = await this.client.resolveEvent(event);
+        return this.client.query(RECOMMENDATIONS, { euid: resolved.euid }, { requireAuth: true, cache: false });
+    }
+    async listConversations(event, options = {}) {
+        const resolved = await this.client.resolveEvent(event);
+        return this.client.query(CONVERSATIONS, { euid: resolved.euid, ...pageVars(options.first, options.after) }, { requireAuth: true, cache: false });
+    }
+    async getConversation(conversationId) {
+        try {
+            const data = await this.client.query(CONVERSATION, { conversationId }, { requireAuth: true, cache: false });
+            if (!data?.conversation) {
+                throw new ConversationNotFoundError();
+            }
+            return data;
+        }
+        catch (error) {
+            if (error instanceof ConversationNotFoundError) {
+                throw error;
+            }
+            if (isConversationNotFound(error)) {
+                throw new ConversationNotFoundError();
+            }
+            throw error;
+        }
+    }
+    async listNotifications(event, options = {}) {
+        const resolved = await this.client.resolveEvent(event);
+        if (!options.list) {
+            return this.client.query(NOTIFICATION_COUNTERS, { euid: resolved.euid }, { requireAuth: true, cache: false });
+        }
+        return this.client.query(NOTIFICATIONS, { euid: resolved.euid, ...pageVars(options.first, options.after), useClientCache: false }, { requireAuth: true, cache: false });
+    }
+    async routeSection(event, section, options = {}) {
+        const resolved = await this.client.resolveEvent(event);
+        const expected = SECTION_TYPENAMES[section];
+        if (options.path?.trim()) {
+            return this.route(resolved.euid, resolveSectionPath(resolved.raw, section, options.path), options.first, options.after);
+        }
+        const paths = candidateSectionPaths(resolved.raw, section);
+        const types = await this.peekRoutes(resolved.euid, paths);
+        const match = paths.find((path) => types.get(path) === expected);
+        if (!match) {
+            return unavailableSection(section);
+        }
+        return this.route(resolved.euid, match, options.first, options.after);
+    }
+    async routeDetail(event, kind, id, explicitPath, first, after) {
+        const resolved = await this.client.resolveEvent(event);
+        const expected = DETAIL_TYPENAMES[kind];
+        let last;
+        for (const path of detailPathCandidates(kind, id, explicitPath)) {
+            last = await this.route(resolved.euid, path, first, after);
+            if (routeTypename(last) === expected) {
+                return last;
+            }
+            if (explicitPath?.trim()) {
+                break;
+            }
+        }
+        return last ?? unavailableSection(kind);
+    }
+    async peekRoutes(euid, paths) {
+        const cached = this.routeTypeCache.get(euid) ?? new Map();
+        const missing = paths.filter((path) => !cached.has(path));
+        if (missing.length > 0) {
+            const data = await this.client.query(buildRouteTypenamesQuery(missing.length), routeTypenameVariables(euid, missing), { cache: true });
+            for (const [path, typename] of parseRouteTypenames(data, missing)) {
+                cached.set(path, typename);
+            }
+            this.routeTypeCache.set(euid, cached);
+        }
+        return new Map(paths.map((path) => [path, cached.get(path)]));
+    }
+    async route(euid, path, first, after) {
+        return this.client.query(DIRECTORY_ROUTE, defaultRouteVariables(euid, path, first, after), { cache: true });
+    }
+}
+function isConversationNotFound(error) {
+    const text = collectErrorText(error);
+    return (text.includes("not found") ||
+        text.includes("couldn't find") ||
+        text.includes("could not find") ||
+        text.includes("requested element is null") ||
+        text.includes("element is null"));
+}
+function collectErrorText(error) {
+    if (error instanceof B2matchGraphQLError) {
+        const extras = Array.isArray(error.errors)
+            ? error.errors
+                .map((item) => {
+                if (item && typeof item === "object" && "message" in item) {
+                    return String(item.message ?? "");
+                }
+                return typeof item === "string" ? item : "";
+            })
+                .join(" ")
+            : "";
+        return `${error.message} ${extras}`.toLowerCase();
+    }
+    if (error instanceof Error) {
+        return error.message.toLowerCase();
+    }
+    return String(error).toLowerCase();
+}

package/dist/auth.d.ts

@@ -0,0 +1,35 @@
+import { SecretBackend } from "./keychain.js";
+export interface StoredAuth {
+    token: string;
+    expiresAt?: string;
+    userId?: string;
+    loginEventId?: string;
+    obtainedVia: "browser" | "paste" | "env" | "password" | "magic-link";
+    savedAt: string;
+}
+export interface AuthState {
+    loggedIn: boolean;
+    source: "env" | "keychain" | "file" | "none";
+    expiresAt?: string;
+    userId?: string;
+    loginEventId?: string;
+    obtainedVia?: StoredAuth["obtainedVia"];
+}
+export declare function configDir(): string;
+export declare function authFilePath(dir?: string): string;
+export declare function decodeJwtExpiry(token: string): string | undefined;
+export declare function isExpired(expiresAt?: string, skewMs?: number): boolean;
+export declare class AuthStore {
+    private readonly dir;
+    private readonly backend;
+    constructor(dir?: string, backend?: SecretBackend | null);
+    read(): Promise<{
+        record: StoredAuth;
+        source: "env" | "keychain" | "file";
+    } | null>;
+    save(record: Omit<StoredAuth, "savedAt" | "expiresAt"> & {
+        expiresAt?: string;
+    }): Promise<"keychain" | "file">;
+    clear(): Promise<void>;
+    status(): Promise<AuthState>;
+}