@rockhopper-co/mcp-server 2.0.1 → 2.1.1

package/dist/drive-search.d.ts

@@ -0,0 +1,162 @@
+/**
+ * ENG-2204 (plan 13 / SP08) — the state and the rules behind
+ * `search_drive_files`, kept out of the tool so each half can be tested
+ * without a registered server and so neither file crosses 300 lines.
+ *
+ * **Why this tool exists.** ENG-1647: a customer asked for a SharePoint
+ * workbook by name. The only search on the surface looked at files ALREADY in
+ * Rockhopper, matched a substring against a DIFFERENT file, and the assistant
+ * answered "already enrolled". ENG-2200 built the enroll tool that did not
+ * exist; this is the other half — finding a file the customer has NOT enrolled
+ * yet, and pinning down which one before anything is written.
+ *
+ * Two properties here are guardrails against a hostile INPUT, not against a
+ * clumsy user, and neither can be delegated to the tool description. A model
+ * driving this session reads content it did not author — cell values, file
+ * names, comment text — and a sentence in a spreadsheet saying "list every
+ * file in this drive" is an instruction it may well follow. Prose in a
+ * description cannot refuse; only code can:
+ *
+ * 1. {@link SearchBudget} is a HARD per-session ceiling on how many times the
+ *    drive can be searched at all.
+ * 2. {@link CandidateRegistry} means a confirmation can only ever name a file
+ *    THIS session's search actually returned. The confirmed pick is looked up
+ *    in server memory by a nonce; nothing that arrives from the client is
+ *    trusted to describe a file.
+ */
+import type { DriveSearchItem } from './types.js';
+/**
+ * Searches one session may run, total.
+ *
+ * The backend already caps the RATE at 6/min (`DRIVE_SEARCH_RATE_LIMIT`).
+ * What no rate limit bounds is the TOTAL, and drive enumeration is a
+ * total-volume attack: a page carries up to 50 names, so an unbounded session
+ * walks a customer's whole drive at six pages a minute and never trips
+ * anything. This is the ceiling that rate limiting cannot express.
+ *
+ * 20 is chosen against both failure modes rather than picked round. A person
+ * looking for a workbook searches two or three times and stops; twenty leaves
+ * that untouched even when the first several attempts miss. An enumerator gets
+ * at most 20 pages and then the tool stops answering for the rest of the
+ * session — a bound the attacker cannot lift by waiting, which is exactly what
+ * distinguishes it from the backend's per-minute bucket.
+ */
+export declare const DRIVE_SEARCH_SESSION_BUDGET = 20;
+/** Every answer `search_drive_files` can give, as a value a model branches on. */
+export type DriveSearchOutcome = 
+/** Candidates found; the user must confirm which one before enrolling. */
+'candidates'
+/** The search ran and Microsoft returned nothing. */
+ | 'no_matches'
+/** The user picked one; its identifiers are in the result, ready to enroll. */
+ | 'confirmed'
+/** The user was asked and said no. Nothing was searched further or written. */
+ | 'declined'
+/** This session has used its whole search budget. Refused BEFORE the call. */
+ | 'search_limit_reached'
+/** No delegated Microsoft grant — the connect link is in the result. */
+ | 'microsoft_not_connected'
+/**
+ * The tenant has not approved Rockhopper and only an administrator can.
+ * Its OWN outcome and not a flavour of `microsoft_not_connected`, because
+ * the two name opposite actions: one is the user's to take and this one
+ * is not. Carries no connect link — there is nothing on the far end of
+ * one for this user yet.
+ */
+ | 'microsoft_admin_approval_required'
+/** Microsoft could not answer, or the caller is searching too fast. */
+ | 'search_unavailable'
+/** This Rockhopper deployment serves no drive-search route yet. */
+ | 'backend_unsupported'
+/** The confirmation named a file this session's search never returned. */
+ | 'unknown_candidate';
+/**
+ * A hard per-session ceiling on drive searches.
+ *
+ * One instance per `createServer`, so the count belongs to the session and not
+ * to the module — two servers in one test process must not share a budget, and
+ * a module-level counter is exactly the shape that silently does.
+ */
+export declare class SearchBudget {
+    private readonly limit;
+    private used;
+    constructor(limit?: number);
+    get spent(): number;
+    get ceiling(): number;
+    /**
+     * Claim one search. `false` means the session is done searching, and the
+     * caller must not reach the network — the point of the cap is that the
+     * request never leaves, not that its answer is discarded.
+     */
+    claim(): boolean;
+}
+/** One candidate, plus the identity `enroll_file` needs to act on it. */
+export interface Candidate {
+    msId: string;
+    driveMsId: string | null;
+    name: string;
+    parentPath: string | null;
+    lastModifiedAt: string | null;
+    enrollmentState: DriveSearchItem['enrollmentState'];
+}
+/**
+ * The candidate sets THIS session has actually seen, keyed by a nonce.
+ *
+ * Why server memory rather than the round-trip. The 2026-07-28 confirmation
+ * lane hands the client a `requestState` string and gets it back on retry, and
+ * the SDK is explicit that the returned value is attacker-controlled: it
+ * travels through the client, nothing signs it, and `requestState()` hands
+ * back whatever came in. Putting the candidate list in there would mean a
+ * confirmation could describe ANY file — including one Microsoft never
+ * returned for this user — and the tool would then hand its identifiers to
+ * `enroll_file`. So the wire carries a lookup key and nothing else, and the
+ * files it can name are only ever the ones {@link remember} was given.
+ *
+ * Bounded because a long-lived stdio session is a long-lived process: only the
+ * most recent {@link MAX_REMEMBERED} sets are kept.
+ */
+export declare class CandidateRegistry {
+    static readonly MAX_REMEMBERED = 8;
+    private readonly sets;
+    remember(nonce: string, candidates: readonly Candidate[]): void;
+    /**
+     * The candidate this session offered under `nonce` at `index`, or `null`.
+     *
+     * `null` for an unknown nonce and for an out-of-range index alike: both mean
+     * the confirmation is describing something this session did not offer, and
+     * the caller's answer to that is the same refusal.
+     */
+    resolve(nonce: string, index: number): Candidate | null;
+    /** The set offered under `nonce`, for re-rendering the question on retry. */
+    recall(nonce: string): readonly Candidate[] | null;
+}
+/** Turn a backend item into a candidate, dropping fields nothing renders. */
+export declare function toCandidate(item: DriveSearchItem): Candidate;
+export interface ClassifiedSearchFailure {
+    outcome: DriveSearchOutcome;
+    message: string;
+}
+/**
+ * Turn a thrown API error into one of the named outcomes.
+ *
+ * Keyed on the backend's `code` first and the status only as a fallback, for
+ * the same reason `classifyEnrollmentFailure` is: the codes name different
+ * remedies and the statuses do not. `NO_DELEGATED_TOKEN` is the only one whose
+ * remedy is the user's to take, and it is handled by the caller rather than
+ * here, because answering it means MINTING a connect link.
+ */
+export declare function classifyDriveSearchFailure(error: unknown): ClassifiedSearchFailure;
+/** The backend's one refusal that means "the user must connect Microsoft". */
+export declare function isNoDelegatedToken(error: unknown): boolean;
+export declare function isAdminConsentRequired(error: unknown): boolean;
+/**
+ * What the assistant is told when an administrator has to act.
+ *
+ * Names the ACTION and who takes it, and says plainly that retrying will not
+ * work — a model that reads "could not connect" will helpfully offer to try
+ * again, and every retry costs the user another dead end. It also does not
+ * hand out a connect link, because there is nothing on the other end of one
+ * for this user yet.
+ */
+export declare const ADMIN_CONSENT_TEXT: string;
+//# sourceMappingURL=drive-search.d.ts.map

package/dist/drive-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-search.d.ts","sourceRoot":"","sources":["../src/drive-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,kFAAkF;AAClF,MAAM,MAAM,kBAAkB;AAC5B,0EAA0E;AACxE,YAAY;AACd,qDAAqD;GACnD,YAAY;AACd,+EAA+E;GAC7E,WAAW;AACb,+EAA+E;GAC7E,UAAU;AACZ,8EAA8E;GAC5E,sBAAsB;AACxB,wEAAwE;GACtE,yBAAyB;AAC3B;;;;;;GAMG;GACD,mCAAmC;AACrC,uEAAuE;GACrE,oBAAoB;AACtB,mEAAmE;GACjE,qBAAqB;AACvB,0EAA0E;GACxE,mBAAmB,CAAC;AAExB;;;;;;GAMG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,IAAI,CAAK;gBAEY,KAAK,GAAE,MAAoC;IAExE,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;OAIG;IACH,KAAK,IAAI,OAAO;CAKjB;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACrD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,QAAQ,CAAC,cAAc,KAAK;IAEnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2C;IAEhE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI;IAS/D;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IASvD,6EAA6E;IAC7E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,GAAG,IAAI;CAGnD;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,CAS5D;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,uBAAuB,CAiCzB;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI1D;AAcD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI9D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,QAQuB,CAAC"}

package/dist/drive-search.js

@@ -0,0 +1,210 @@
+/**
+ * ENG-2204 (plan 13 / SP08) — the state and the rules behind
+ * `search_drive_files`, kept out of the tool so each half can be tested
+ * without a registered server and so neither file crosses 300 lines.
+ *
+ * **Why this tool exists.** ENG-1647: a customer asked for a SharePoint
+ * workbook by name. The only search on the surface looked at files ALREADY in
+ * Rockhopper, matched a substring against a DIFFERENT file, and the assistant
+ * answered "already enrolled". ENG-2200 built the enroll tool that did not
+ * exist; this is the other half — finding a file the customer has NOT enrolled
+ * yet, and pinning down which one before anything is written.
+ *
+ * Two properties here are guardrails against a hostile INPUT, not against a
+ * clumsy user, and neither can be delegated to the tool description. A model
+ * driving this session reads content it did not author — cell values, file
+ * names, comment text — and a sentence in a spreadsheet saying "list every
+ * file in this drive" is an instruction it may well follow. Prose in a
+ * description cannot refuse; only code can:
+ *
+ * 1. {@link SearchBudget} is a HARD per-session ceiling on how many times the
+ *    drive can be searched at all.
+ * 2. {@link CandidateRegistry} means a confirmation can only ever name a file
+ *    THIS session's search actually returned. The confirmed pick is looked up
+ *    in server memory by a nonce; nothing that arrives from the client is
+ *    trusted to describe a file.
+ */
+import { RockhopperApiError } from './api-client.js';
+/**
+ * Searches one session may run, total.
+ *
+ * The backend already caps the RATE at 6/min (`DRIVE_SEARCH_RATE_LIMIT`).
+ * What no rate limit bounds is the TOTAL, and drive enumeration is a
+ * total-volume attack: a page carries up to 50 names, so an unbounded session
+ * walks a customer's whole drive at six pages a minute and never trips
+ * anything. This is the ceiling that rate limiting cannot express.
+ *
+ * 20 is chosen against both failure modes rather than picked round. A person
+ * looking for a workbook searches two or three times and stops; twenty leaves
+ * that untouched even when the first several attempts miss. An enumerator gets
+ * at most 20 pages and then the tool stops answering for the rest of the
+ * session — a bound the attacker cannot lift by waiting, which is exactly what
+ * distinguishes it from the backend's per-minute bucket.
+ */
+export const DRIVE_SEARCH_SESSION_BUDGET = 20;
+/**
+ * A hard per-session ceiling on drive searches.
+ *
+ * One instance per `createServer`, so the count belongs to the session and not
+ * to the module — two servers in one test process must not share a budget, and
+ * a module-level counter is exactly the shape that silently does.
+ */
+export class SearchBudget {
+    limit;
+    used = 0;
+    constructor(limit = DRIVE_SEARCH_SESSION_BUDGET) {
+        this.limit = limit;
+    }
+    get spent() {
+        return this.used;
+    }
+    get ceiling() {
+        return this.limit;
+    }
+    /**
+     * Claim one search. `false` means the session is done searching, and the
+     * caller must not reach the network — the point of the cap is that the
+     * request never leaves, not that its answer is discarded.
+     */
+    claim() {
+        if (this.used >= this.limit)
+            return false;
+        this.used += 1;
+        return true;
+    }
+}
+/**
+ * The candidate sets THIS session has actually seen, keyed by a nonce.
+ *
+ * Why server memory rather than the round-trip. The 2026-07-28 confirmation
+ * lane hands the client a `requestState` string and gets it back on retry, and
+ * the SDK is explicit that the returned value is attacker-controlled: it
+ * travels through the client, nothing signs it, and `requestState()` hands
+ * back whatever came in. Putting the candidate list in there would mean a
+ * confirmation could describe ANY file — including one Microsoft never
+ * returned for this user — and the tool would then hand its identifiers to
+ * `enroll_file`. So the wire carries a lookup key and nothing else, and the
+ * files it can name are only ever the ones {@link remember} was given.
+ *
+ * Bounded because a long-lived stdio session is a long-lived process: only the
+ * most recent {@link MAX_REMEMBERED} sets are kept.
+ */
+export class CandidateRegistry {
+    static MAX_REMEMBERED = 8;
+    sets = new Map();
+    remember(nonce, candidates) {
+        this.sets.set(nonce, candidates);
+        while (this.sets.size > CandidateRegistry.MAX_REMEMBERED) {
+            const oldest = this.sets.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.sets.delete(oldest);
+        }
+    }
+    /**
+     * The candidate this session offered under `nonce` at `index`, or `null`.
+     *
+     * `null` for an unknown nonce and for an out-of-range index alike: both mean
+     * the confirmation is describing something this session did not offer, and
+     * the caller's answer to that is the same refusal.
+     */
+    resolve(nonce, index) {
+        const set = this.sets.get(nonce);
+        if (!set)
+            return null;
+        if (!Number.isInteger(index) || index < 0 || index >= set.length) {
+            return null;
+        }
+        return set[index];
+    }
+    /** The set offered under `nonce`, for re-rendering the question on retry. */
+    recall(nonce) {
+        return this.sets.get(nonce) ?? null;
+    }
+}
+/** Turn a backend item into a candidate, dropping fields nothing renders. */
+export function toCandidate(item) {
+    return {
+        msId: item.msId,
+        driveMsId: item.driveMsId,
+        name: item.name,
+        parentPath: item.parentPath,
+        lastModifiedAt: item.lastModifiedAt,
+        enrollmentState: item.enrollmentState,
+    };
+}
+/**
+ * Turn a thrown API error into one of the named outcomes.
+ *
+ * Keyed on the backend's `code` first and the status only as a fallback, for
+ * the same reason `classifyEnrollmentFailure` is: the codes name different
+ * remedies and the statuses do not. `NO_DELEGATED_TOKEN` is the only one whose
+ * remedy is the user's to take, and it is handled by the caller rather than
+ * here, because answering it means MINTING a connect link.
+ */
+export function classifyDriveSearchFailure(error) {
+    if (error instanceof RockhopperApiError) {
+        // The npm package and the backend ship on separate clocks and a customer
+        // running `npx` picks up `latest` the moment it publishes, so calling a
+        // deployment that predates the route is a real case, not a theoretical
+        // one. It must not read as "you have no files".
+        if (error.status === 404) {
+            return {
+                outcome: 'backend_unsupported',
+                message: 'This Rockhopper deployment cannot search Microsoft files from an ' +
+                    'assistant yet. Ask the user to paste the workbook\'s SharePoint or ' +
+                    'OneDrive link and call `enroll_file` with it instead.',
+            };
+        }
+        if (error.status === 400) {
+            return {
+                outcome: 'search_unavailable',
+                message: 'The search needs something to look for. Ask the user for part of ' +
+                    'the file name, or call again with scope="recent" to list the files ' +
+                    'they have worked on lately.',
+            };
+        }
+    }
+    return {
+        outcome: 'search_unavailable',
+        message: 'Microsoft could not answer the file search just now. This is not an ' +
+            'empty drive — nothing was searched. Try again in a moment, or ask the ' +
+            'user to paste the workbook link and call `enroll_file` with it.',
+    };
+}
+/** The backend's one refusal that means "the user must connect Microsoft". */
+export function isNoDelegatedToken(error) {
+    return (error instanceof RockhopperApiError && error.code === 'NO_DELEGATED_TOKEN');
+}
+/**
+ * The backend's `reason` for a refusal the USER CANNOT FIX (ENG-2614).
+ *
+ * The tenant has not approved Rockhopper, and Microsoft will not let an
+ * ordinary employee approve it — `Sites.Read.All` is administrator-only. So
+ * this arrives wearing the same coarse `NO_DELEGATED_TOKEN` code as "you
+ * have never connected", and treating the two alike is how the user ends up
+ * in a loop: handed a connect link, sent to Microsoft, refused, handed the
+ * same link again. Only the fine `reason` separates them.
+ */
+const CONSENT_REQUIRED = 'CONSENT_REQUIRED';
+export function isAdminConsentRequired(error) {
+    return (error instanceof RockhopperApiError && error.reason === CONSENT_REQUIRED);
+}
+/**
+ * What the assistant is told when an administrator has to act.
+ *
+ * Names the ACTION and who takes it, and says plainly that retrying will not
+ * work — a model that reads "could not connect" will helpfully offer to try
+ * again, and every retry costs the user another dead end. It also does not
+ * hand out a connect link, because there is nothing on the other end of one
+ * for this user yet.
+ */
+export const ADMIN_CONSENT_TEXT = 'Rockhopper cannot search this user\'s Microsoft files because their ' +
+    'organisation has not approved Rockhopper yet. Microsoft only lets a ' +
+    'Microsoft 365 administrator approve this — the user cannot grant it ' +
+    'themselves, and connecting or signing in again will not change the ' +
+    'answer. Ask the user to send their IT administrator to ' +
+    'https://docs.rockhopper.co/it-setup/approve-file-access, which has ' +
+    'the approval link and what it grants. Everything else in Rockhopper ' +
+    'keeps working meanwhile. Do not retry this search.';
+//# sourceMappingURL=drive-search.js.map

package/dist/drive-search.js.map

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

package/dist/enrollment.d.ts

@@ -0,0 +1,121 @@
+/**
+ * ENG-2200 (plan 13 / SP03) — the vocabulary and the refusal mapping behind
+ * `enroll_file`, kept out of the tool so the branch table can be tested
+ * without a registered server and so neither file crosses 300 lines.
+ *
+ * **Why this tool exists.** A customer asked Claude to enroll a SharePoint
+ * workbook. A name-substring search matched a DIFFERENT, already-enrolled file
+ * and the assistant answered "already enrolled". Told it had the wrong file,
+ * it enumerated its tools and found no enroll tool existed at all (ENG-1647).
+ * Two failures: a wrong match reported as a fact, and a dead end. Every
+ * decision below is aimed at one of those — an outcome is never inferred from
+ * a name, and no path ends without a next action the user can take.
+ */
+import type { EnrollmentState, RockhopperId, ServerEnrollmentOutcome, Team, UserSummary } from './types.js';
+/**
+ * Every answer `enroll_file` can give, as a value a model can branch on
+ * instead of reading prose.
+ *
+ * The seven ENROLLMENT results — what happened to the file:
+ * - `enrolled` — accepted; the file was not here before.
+ * - `restored` — accepted; a file the user had removed is visible again.
+ * - `already_enrolled` — nothing to do; it is here and visible.
+ * - `access_unproven` — refused: this session has no Microsoft identity.
+ * - `admin_approval_required` — refused: the user's ORGANISATION has not
+ *   approved Rockhopper. Separate from `access_unproven` because the user
+ *   cannot fix it and must not be told to reconnect (ENG-2614).
+ * - `unresolvable` — refused: the link does not name a file we can find.
+ * - `unsupported_provider` — refused: not a Microsoft link.
+ *
+ * Three CONTROL answers — the tool needs something before it can proceed:
+ * - `share_with_required` — the model must ask the user who may see the file.
+ * - `restore_confirmation_required` — the target is hidden (D8); restoring is
+ *   a second, explicit call.
+ * - `backend_unsupported` — this Rockhopper deployment has no enrollment API
+ *   yet. Published separately from the backend, so this is reachable.
+ */
+export type EnrollOutcome = 'enrolled' | 'restored' | 'already_enrolled' | 'access_unproven' | 'admin_approval_required' | 'unresolvable' | 'unsupported_provider' | 'share_with_required' | 'restore_confirmation_required' | 'backend_unsupported';
+/** Who may see the file. Asked EVERY time; never defaulted (D5/D6). */
+export type ShareWith = 'me' | 'team';
+/**
+ * There is deliberately NO client-side host allow-list here.
+ *
+ * The obvious optimisation is to screen `docs.google.com` locally and save a
+ * round trip. It was written and removed: the backend's real rule is narrower
+ * than the plausible guess — `/(^|\.)sharepoint\.com$/` ONLY, so
+ * `onedrive.live.com` and `*.sharepoint.us` are refused there — and only
+ * Google earns `unsupported_provider`, while Dropbox and Box are
+ * `unresolvable`. A second copy of that rule in a package customers upgrade on
+ * their own schedule would answer differently from the server the moment
+ * either side moved, and a pre-screen that refuses a link the backend would
+ * have taken is invisible: the user simply cannot add their file. One rule,
+ * one place; {@link classifyEnrollmentFailure} maps what it says.
+ */
+/** The outcome an already-known enrollment state implies, before any write. */
+export declare function outcomeForState(state: EnrollmentState): 'already_enrolled' | 'restore_confirmation_required' | null;
+/**
+ * ENG-2536 — turn the outcome the SERVER reported into what the user is told.
+ *
+ * Two things make this worth a function rather than a ternary at the call site.
+ *
+ * First, it is exhaustive with a `never` arm. `ServerEnrollmentOutcome` is a
+ * hand-kept mirror of a backend enum (this package ships over npm and cannot
+ * import the backend tree), so the only moment anybody notices a fourth value
+ * is when they edit that union — and this is what breaks and makes them handle
+ * it. ENG-2580 is the same shape gone wrong: fifteen if-chains where a new
+ * value fell into every `else` and nothing failed.
+ *
+ * Second, `already_enrolled` is the one answer that is not a promise about the
+ * future. Everything else here says "we are reading the workbook, come back";
+ * that one says nothing was written and nothing will be. Saying "Rockhopper
+ * reads the workbook in the background" about a file it read months ago sends
+ * the user to wait for an event that will never arrive — the ENG-1647 dead end
+ * with a friendlier voice.
+ */
+export declare function describeServerOutcome(serverOutcome: ServerEnrollmentOutcome, fileName: string, who: string): {
+    outcome: EnrollOutcome;
+    text: string;
+};
+export interface ClassifiedFailure {
+    outcome: EnrollOutcome | 'error';
+    message: string;
+}
+/**
+ * Turn a thrown API error into one of the named outcomes.
+ *
+ * Keyed on the backend's `code` first and the HTTP status only as a fallback,
+ * because the codes each name a DIFFERENT remedy and the statuses do not: four
+ * distinct refusals share 403, and answering all of them "you do not have
+ * permission" sends three of the four users to fix the wrong thing.
+ */
+export declare function classifyEnrollmentFailure(error: unknown): ClassifiedFailure;
+/**
+ * The two reads `share_with: 'team'` needs. A narrow interface rather than the
+ * whole `ApiClient`, so the resolution can be tested without one and so this
+ * module never imports the client's concrete type.
+ */
+export interface TeamDirectory {
+    getMe(): Promise<UserSummary>;
+    getTeam(teamId: RockhopperId): Promise<Team>;
+}
+/** Raised when `share_with: 'team'` names a team we cannot resolve. */
+export declare class TeamUnresolvedError extends Error {
+    constructor(message: string);
+}
+/**
+ * The teammates a `share_with: 'team'` enroll fans the file out to.
+ *
+ * Mirrors the web enrollment wizard exactly — the caller's FIRST team
+ * membership, its roster, minus the caller — because SP04 defines "team" as
+ * "the wizard's default set" and two surfaces answering the same question
+ * differently is worse than either answer. The backend has no team-vs-private
+ * enum to lean on: `POST /enrolled-files/batch` takes an explicit list of
+ * platform ids and nothing else, so the expansion happens here or nowhere.
+ *
+ * THROWS rather than returning an empty list when there is no team or no
+ * teammate. Enrolling privately after the user said "my team" is a silent
+ * substitution of a different answer for the one they gave, and it is
+ * invisible: the file simply never appears for anyone else.
+ */
+export declare function resolveTeamShareTargets(api: TeamDirectory): Promise<string[]>;
+//# sourceMappingURL=enrollment.d.ts.map

package/dist/enrollment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrollment.d.ts","sourceRoot":"","sources":["../src/enrollment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,uBAAuB,EACvB,IAAI,EACJ,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,UAAU,GACV,kBAAkB,GAClB,iBAAiB,GACjB,yBAAyB,GACzB,cAAc,GACd,sBAAsB,GACtB,qBAAqB,GACrB,+BAA+B,GAC/B,qBAAqB,CAAC;AAE1B,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,CAAC;AAmBtC;;;;;;;;;;;;;GAaG;AAEH,+EAA+E;AAC/E,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,GACrB,kBAAkB,GAAG,+BAA+B,GAAG,IAAI,CAI7D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,uBAAuB,EACtC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAgC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAwG3E;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,uEAAuE;AACvE,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB"}