@ttctl/core 0.1.0-rc.7 → 0.1.0-rc.8

package/dist/services/applications/index.d.ts

@@ -1,4 +1,8 @@
+import type { JobExpertiseAnswerInput, JobPositionAnswerInput, PitchInput } from "../../__generated__/zod-schemas.js";
+import { JobExpertiseAnswerInputSchema, JobPositionAnswerInputSchema, PitchInputSchema } from "../../__generated__/zod-schemas.js";
 import type { DryRunPreview } from "../../transport.js";
+export type { JobExpertiseAnswerInput, JobPositionAnswerInput, PitchInput };
+export { JobExpertiseAnswerInputSchema, JobPositionAnswerInputSchema, PitchInputSchema };
 /**
  * Applications-domain error codes. Mirrors the `ProfileError` /
  * `SkillsError` shape per project convention so each sub-domain carries
@@ -14,7 +18,25 @@ import type { DryRunPreview } from "../../transport.js";
  * `NOT_FOUND` so the CLI can render a "no such application" line and
  * the MCP tool can return a structured `(NOT_FOUND)` error response.
  */
-export type ApplicationsErrorCode = "NO_VIEWER" | "NOT_FOUND" | "GRAPHQL_ERROR" | "MUTATION_ERROR" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR" | "UNKNOWN";
+export type ApplicationsErrorCode = "NO_VIEWER" | "NOT_FOUND" | "GRAPHQL_ERROR" | "MUTATION_ERROR" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR"
+/**
+ * Direct-apply consent gate (#426). The wire's `consentIssued: Boolean!`
+ * is a legal-compliance attestation; the service refuses to issue the
+ * mutation unless the caller explicitly passes `consentIssued: true`
+ * on {@link ApplyInput}. Same posture #411 took on the DESTRUCTIVE
+ * IR mutations, with the legal dimension added. Fired before any wire
+ * call.
+ */
+ | "CONSENT_REQUIRED"
+/**
+ * Direct-apply double-application gate (#426). The wire returns
+ * `success: false` with `errors[].key === "already_applied"` when the
+ * talent has previously applied to the same job. Mapped to a typed
+ * code so callers (CLI / MCP / agents) can surface a "you already
+ * applied" hint pointing at `ttctl applications show <activity-id>`
+ * instead of the generic `MUTATION_ERROR` envelope.
+ */
+ | "ALREADY_APPLIED" | "UNKNOWN";
 export declare class ApplicationsError extends Error {
     readonly code: ApplicationsErrorCode;
     readonly name = "ApplicationsError";
@@ -260,13 +282,17 @@ export interface AvailabilityRequestRespondPayload {
  *   {@link AvailabilityRequestKind} for the value spellings.
  * - `comment` (optional) — the talent's free-text accompanying message.
  *   Mapped to the wire's `talentComment` field.
- * - `matcherQuestionsAnswers`, `expertiseQuestionsAnswers`, `pitchData`
+ * - `matcherQuestionsAnswers`, `expertiseQuestionsAnswers`, `pitchInput`
  *   (optional) — structural inputs for AR confirmations that require
- *   matcher / expertise question answers or a custom pitch. These are
- *   wire pass-throughs; the service does NOT introspect them. v1
- *   exposes them as `unknown` arrays — callers passing them are
- *   responsible for the wire shape (`JobPositionAnswerInput[]`,
- *   `JobExpertiseAnswerInput[]`, `PitchInput`).
+ *   matcher / expertise question answers or a custom pitch. Stage-2
+ *   (#438) types these against the recovered SDL shapes —
+ *   {@link JobPositionAnswerInput}, {@link JobExpertiseAnswerInput},
+ *   {@link PitchInput} (regenerated from #425's recovery output).
+ *   `matcherQuestionsAnswers` entries use `id` (NOT `questionId`) per
+ *   the SDL; `expertiseQuestionsAnswers` entries use `questionId`.
+ *   The service still passes them through to the wire opaquely; the
+ *   typing is the boundary contract for CLI / MCP / direct-Core
+ *   callers.
  */
 export interface ConfirmInput {
     /** Optional talent-side free-text message. Wire field: `talentComment`. */
@@ -275,12 +301,12 @@ export interface ConfirmInput {
     requestedHourlyRate?: string;
     /** AR kind. Auto-detected from `metadata.__typename` when omitted. INFERRED enum values — see {@link AvailabilityRequestKind}. */
     kind?: AvailabilityRequestKind;
-    /** Optional matcher-questions answers (`JobPositionAnswerInput[]`). v1: opaque pass-through. */
-    matcherQuestionsAnswers?: unknown[];
-    /** Optional expertise-questions answers (`JobExpertiseAnswerInput[]`). v1: opaque pass-through. */
-    expertiseQuestionsAnswers?: unknown[];
-    /** Optional pitch input (`PitchInput`). v1: opaque pass-through. */
-    pitchInput?: Record<string, unknown>;
+    /** Optional matcher-questions answers — wire shape `JobPositionAnswerInput[]` (`{ id, answer }`). */
+    matcherQuestionsAnswers?: JobPositionAnswerInput[];
+    /** Optional expertise-questions answers — wire shape `JobExpertiseAnswerInput[]` (`{ questionId, other, subjectId }`). */
+    expertiseQuestionsAnswers?: JobExpertiseAnswerInput[];
+    /** Optional pitch input — wire shape `PitchInput`. */
+    pitchInput?: PitchInput;
 }
 /**
  * Input for {@link reject}. The wire mutation's input takes
@@ -473,6 +499,259 @@ export declare function show(token: string, id: string): Promise<JobActivityItem
  * user knows exactly what went wrong.
  */
 export declare function stats(token: string): Promise<ApplicationsStats>;
+/**
+ * One entry of `viewer.job.operations.apply.errors` (#424). Schema
+ * declares both fields as `String!` — non-null — but the projection
+ * helper {@link projectApplyErrors} keeps a defensive list-entry null
+ * filter because the WIRE shape on the schema-gap path (this op is in
+ * `GATEWAY_MOBILE_KNOWN_UNTRUSTED_OPS`) is best-effort.
+ */
+export interface ApplyError {
+    code: string;
+    message: string;
+}
+/**
+ * Aggregate pre-apply context returned by {@link applyData} (#424).
+ *
+ * Surfaces the load-bearing scalars from the captured `JobApplyData`
+ * operation — the suggested rate (REQ-A4), platform validation
+ * bounds, the apply-state errors, and basic job context — trimmed of
+ * the heavy pitch / talent-card / market-condition cascades the
+ * captured op also pulls in. Downstream consumers:
+ *
+ *   - **#426 (apply core fn)** — reads `canApply` to short-circuit
+ *     before the mutation, uses `suggestedRate` as the
+ *     `requestedHourlyRate` default, validates against `rateValidation`.
+ *   - **#437 (`jobs show`)** — surfaces `applyErrors` so the user can
+ *     see WHY they can't apply (already applied, job closed, etc.)
+ *     directly on the job-detail view.
+ *
+ * `canApply` is a convenience boolean derived from
+ * `applyErrors.length === 0` — kept as a separate field so callers
+ * don't have to recompute it.
+ */
+export interface PreApplyData {
+    job: {
+        id: string;
+        isCoaching: boolean | null;
+        hasRequiredApplicationPitch: boolean | null;
+    };
+    /** Empty when the talent may apply; populated lists the blocking reasons. */
+    applyErrors: ApplyError[];
+    /** Convenience: `true` iff `applyErrors` is empty. */
+    canApply: boolean;
+    /**
+     * Talent's configured hourly rate (`viewerRole.rates.hourly`). The
+     * apply path uses this as the `requestedHourlyRate` default
+     * (REQ-A4). `null` when the viewerRole is absent (defensive — the
+     * schema declares `ViewerRole.rates.hourly: String!`, but absence
+     * is treated as null projection rather than a hard error).
+     */
+    suggestedRate: string | null;
+    /**
+     * Platform hourly-rate validation bounds. `null` when the platform
+     * configuration block is absent (defensive — the schema declares
+     * `PlatformConfiguration.rateValidationRules: TalentRateValidationRules!`
+     * non-null, but gateway-side absence is surfaced as null projection
+     * rather than a hard error). Note `rateStep` is `Int` on the wire,
+     * not a decimal string.
+     */
+    rateValidation: {
+        minRate: string;
+        rateStep: number;
+    } | null;
+}
+/**
+ * One question on the apply form (#424). The four-field shape is
+ * uniform across matcher and expertise variants per REQ-Q1:
+ *
+ *   - `identifier` — the wire `id` field (`JobPositionQuestion.id` /
+ *     `JobExpertiseQuestion.id`). Threaded into the apply-mutation
+ *     answer arrays at asymmetric field names per the recovered SDL:
+ *     `JobPositionAnswerInput.id` (matcher) and
+ *     `JobExpertiseAnswerInput.questionId` (expertise). Both reference
+ *     this same `identifier`; see ADR-008 § Decision Part 2 and #438
+ *     for the recovered-shape rationale.
+ *   - `prompt` — the human-readable question text. For matcher
+ *     questions: the wire `question` field. For expertise questions:
+ *     the `subject.name` (`Industry.name` or `Skill.name`) — expertise
+ *     questions ask "which of your profile items demonstrates this
+ *     skill / industry?", so the subject's name IS the prompt the
+ *     user sees.
+ *   - `type` — TTCtl-side discriminant `"matcher" | "expertise"`,
+ *     making each question self-describing if consumers flatten the
+ *     two arrays (e.g., #426's answers-file template builder).
+ *   - `isMandatory` — for matcher questions, the wire `isRequired`
+ *     field. For expertise questions: projected as `true`. The
+ *     captured `JobApplicationQuestions` operation selects no
+ *     per-question mandatory flag on `expertiseQuestions` (and the
+ *     synthesized schema doesn't even declare `JobExpertiseQuestion`),
+ *     but the `JobApply` mutation takes
+ *     `$expertiseQuestionsAnswers: [JobExpertiseAnswerInput!]` as a
+ *     required apply-payload field (research note
+ *     `03-applications.md` § Apply flow specifics: "Both question
+ *     types ... must be fetched first ... The client cannot guess
+ *     them"). Documented inference; #445 live E2E is the wire
+ *     authority and may refine this projection if real data surfaces
+ *     a more nuanced mandatory-ness signal.
+ */
+export interface ApplicationQuestion {
+    identifier: string;
+    prompt: string;
+    type: "matcher" | "expertise";
+    isMandatory: boolean;
+}
+/**
+ * Questions inventory returned by {@link applyQuestions} (#424).
+ * Mirrors the captured `JobApplicationQuestions` operation's two
+ * parallel selections — `viewer.job.questions(hideExpertiseQuestion:
+ * true)` for matcher questions, `viewer.job.expertiseQuestions` for
+ * expertise — projecting each entry to the four-field
+ * {@link ApplicationQuestion} shape. Empty arrays surface verbatim
+ * when the job has no questions of that kind.
+ */
+export interface ApplicationQuestions {
+    matcherQuestions: ApplicationQuestion[];
+    expertiseQuestions: ApplicationQuestion[];
+}
+/**
+ * Rate insight when the talent's rate (or default rate) is judged
+ * COMPETITIVE relative to the job's market (#424). Discriminated-union
+ * member of {@link RateInsight}; surfaces the captured wire's
+ * `TalentJobRateInsightCompetitive` fields verbatim.
+ *
+ * All revenue / rate fields are `BigDecimal` decimal-string scalars
+ * per the captured wire (the captured
+ * `JobApplicationRateInsight.graphql` operation selects them bare,
+ * no `{ }` sub-selection; the synthesized schema confirms
+ * `BigDecimal`). They are NOT a `Money { decimal verbose }` shape —
+ * see PR body for the deviation from the issue parenthetical.
+ */
+export interface CompetitiveRateInsight {
+    kind: "competitive";
+    /** Estimated revenue at the supplied rate (BigDecimal scalar). */
+    estimatedRevenue: string | null;
+    /** Server-localised prose explaining the revenue estimate. */
+    estimatedRevenueExplanation: string | null;
+    /** Server-localised disclaimer about long-term engagement assumptions. */
+    longTermDisclaimer: string | null;
+}
+/**
+ * Rate insight when the talent's rate (or default rate) is judged
+ * UNCOMPETITIVE relative to the job's market (#424).
+ * Discriminated-union member of {@link RateInsight}; surfaces the
+ * captured wire's `TalentJobRateInsightUncompetitive` fields verbatim.
+ *
+ * `recentApplicationRate` + `recommendedRate` together form the
+ * "range guidance" the apply path uses to inform the talent
+ * (`recentApplicationRate` = empirical rate of recent successful
+ * applicants on this specific job; `recommendedRate` = Toptal's
+ * suggested rate to be competitive). Both are `BigDecimal`
+ * decimal-string scalars on the wire.
+ */
+export interface UncompetitiveRateInsight {
+    kind: "uncompetitive";
+    estimatedRevenue: string | null;
+    estimatedRevenueExplanation: string | null;
+    /** Empirical rate of recent successful applicants (BigDecimal scalar). */
+    recentApplicationRate: string | null;
+    /** Toptal's suggested rate to be competitive (BigDecimal scalar). */
+    recommendedRate: string | null;
+}
+/**
+ * Discriminated-union projection of the wire's `TalentJobRateInsight`
+ * union (members `TalentJobRateInsightCompetitive` |
+ * `TalentJobRateInsightUncompetitive`). The `kind` discriminant
+ * narrows access to the variant-specific fields. Returned by
+ * {@link rateInsight}; `null` when the gateway omits the rate-insight
+ * payload (viewer null, job null, or `rateInsight` field null).
+ */
+export type RateInsight = CompetitiveRateInsight | UncompetitiveRateInsight;
+/**
+ * Pre-apply aggregate context for a job (#424). Wraps `JobApplyData
+ * ($jobId)` — the mobile gateway's aggregate pre-apply query — and
+ * trims the response to the load-bearing scalars (REQ-A4 rate
+ * default, apply-state errors, platform validation bounds, plus
+ * basic job context). The captured operation also pulls in the
+ * pitch / talent-card / market-condition cascades; those are
+ * deliberately elided here. The apply path (#426) takes the pitch
+ * from `--pitch-file` per ADR-008's grammar, NOT from
+ * `suggestedPitch` / `lastPitches`, and `applyQuestions` /
+ * `rateInsight` cover the other captured slices. Future widening is
+ * additive.
+ *
+ * **Wire authority**: hand-authored from the captured
+ * `JobApplyData.graphql` selection set; CLAUDE.md schema/contract
+ * rule TRIGGERED for #424, live E2E coverage in #445.
+ *
+ * **Bad-id behavior**: `viewer.job(id:)` returns the Relay decode
+ * error (per `project-toptal-wire-quirks` memory) when the supplied
+ * id doesn't resolve to a viewable job; remapped to
+ * `ApplicationsError("NOT_FOUND")` via the shared
+ * {@link NOT_FOUND_MESSAGE_PATTERN} (widened in #424).
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` when the job id doesn't
+ *   resolve (Relay decode error, `Invalid ID`, `Record not found`,
+ *   or successful response with `viewer.job === null`).
+ * @throws `ApplicationsError("NO_VIEWER")` when the session is valid
+ *   but no viewer is bound (defensive — `callGateway` with
+ *   `requireViewer: true` already raises this case, but the
+ *   post-call null check keeps the type narrowing clean).
+ */
+export declare function applyData(token: string, jobId: string): Promise<PreApplyData>;
+/**
+ * Pre-apply matcher + expertise questions inventory for a job (#424).
+ * Wraps `JobApplicationQuestions($jobId)`; trims the captured
+ * operation's `subject.possibleAnswers` cascades — the four-field
+ * {@link ApplicationQuestion} shape is the public projection per
+ * #424 AC.
+ *
+ * The two arrays surface verbatim presence: empty when the job has
+ * no questions of that kind. Order is server-supplied; no
+ * client-side re-sorting.
+ *
+ * **Bad-id behavior + NOT_FOUND mapping**: identical to
+ * {@link applyData}.
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` for unresolved job ids.
+ * @throws `ApplicationsError("NO_VIEWER")` for sessions with no
+ *   bound viewer.
+ */
+export declare function applyQuestions(token: string, jobId: string): Promise<ApplicationQuestions>;
+/**
+ * Pre-apply rate guidance for a job (#424). Wraps
+ * `JobApplicationRateInsight($jobId)`; surfaces the captured
+ * operation's `TalentJobRateInsight` discriminated union as
+ * {@link RateInsight}. Returns `null` when the gateway omits the
+ * insight payload (the `rateInsight` field on the job resolves to
+ * null).
+ *
+ * The operation declares `$requestedRate: BigDecimal` (verbatim from
+ * the captured wire) but the public signature does NOT expose
+ * `requestedRate` per #424 AC — the variable is threaded as `null`,
+ * which the gateway treats as "show me the insight for the talent's
+ * default rate". Re-exposing the parameter is a future widening.
+ *
+ * **Wire shape**: union members carry `BigDecimal` scalar fields
+ * (`estimatedRevenue`, `recommendedRate`, `recentApplicationRate`)
+ * — NOT `Money { decimal verbose }` objects. The captured
+ * `JobApplicationRateInsight.graphql` operation selects them bare
+ * (no sub-selection), and the synthesized schema confirms
+ * `BigDecimal`. The #424 issue parenthetical "Money shape `{ decimal,
+ * verbose }` + range guidance" reflects an intuition rather than the
+ * captured wire; the captured operation's selection set is
+ * authoritative per the issue's own primary directive ("define shape
+ * based on captured operation's selection set"). PR body documents
+ * the deviation.
+ *
+ * **Bad-id behavior + NOT_FOUND mapping**: identical to
+ * {@link applyData}.
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` for unresolved job ids.
+ * @throws `ApplicationsError("NO_VIEWER")` for sessions with no
+ *   bound viewer.
+ */
+export declare function rateInsight(token: string, jobId: string): Promise<RateInsight | null>;
 /**
  * Confirm an Interest Request — wire `ConfirmAvailabilityRequest` (#411).
  *
@@ -536,4 +815,629 @@ export declare function reject(token: string, id: string, input: RejectInput, op
  * field is non-null in the schema; absence is wire-shape drift).
  */
 export declare function rejectReasons(token: string): Promise<AvailabilityRequestRejectReasons>;
+/**
+ * Input for {@link apply}. Field names mirror ADR-008's locked grammar
+ * (`matcherAnswers` / `expertiseAnswers` / `pitchData` / `message`)
+ * which is the MCP-side schema key set, NOT the wire-side variable
+ * names (`matcherQuestionsAnswers`, `expertiseQuestionsAnswers`,
+ * `talentCard`, `comment`). The service maps the public field names
+ * onto the wire variables internally.
+ *
+ * **Consent gate**: `consentIssued` is the literal `true` — the
+ * tightest type-system constraint TS supports, matching ADR-008
+ * § Decision Part 4. The runtime check covers `as`-cast bypasses
+ * and JSON-sourced inputs from the CLI/MCP layers where the type
+ * system can't reach. Auto-filling consent on the caller's behalf is
+ * FORBIDDEN by the same ADR; the service throws
+ * `CONSENT_REQUIRED` BEFORE any wire call when omitted.
+ *
+ * **Rate default**: `requestedHourlyRate` is optional at the input
+ * surface. When omitted, the service threads
+ * `PreApplyData.suggestedRate` (the talent's own configured rate
+ * `viewerRole.rates.hourly`) into the mutation per REQ-A4. If the
+ * talent has no configured rate, the service throws `MUTATION_ERROR`.
+ * The `rateInsight` payload returned by the pre-fetch suite serves as
+ * additional guidance for the caller (CLI / MCP / agent) — not as a
+ * silent default; callers surface it to the user before the apply.
+ *
+ * **Answer arrays**: `matcherAnswers` / `expertiseAnswers` are typed
+ * against the recovered `JobPositionAnswerInput[]` /
+ * `JobExpertiseAnswerInput[]` shapes (Stage 2 per #438; the recovered
+ * schemas are committed in `packages/core/src/__generated__/zod-schemas.ts`).
+ * The service validates each entry's id field against the inventory
+ * returned by `applyQuestions(jobId)` and rejects unknown ids with
+ * `WIRE_SHAPE_ERROR`. The id-field name is **asymmetric** per the
+ * recovered SDL — matcher entries carry `id`, expertise entries carry
+ * `questionId`.
+ */
+export interface ApplyInput {
+    /**
+     * Consent attestation — MUST be the literal `true`. Auto-filling
+     * this field on the caller's behalf is FORBIDDEN per ADR-008
+     * § Decision Part 4 (legal compliance).
+     */
+    consentIssued: true;
+    /**
+     * Hourly rate the talent requests for this engagement. Decimal
+     * string (matches `BigDecimal!`). When omitted, the service
+     * defaults from `PreApplyData.suggestedRate` (REQ-A4).
+     */
+    requestedHourlyRate?: string;
+    /**
+     * Optional talent-side free-text accompanying message. Mapped to
+     * the wire's `$comment` variable / `JobApplyInput.comment` field.
+     */
+    message?: string;
+    /**
+     * Matcher-question answers (`JobPositionAnswerInput[]`). Each
+     * entry MUST carry an `id` field matching one returned from
+     * `applyQuestions(jobId).matcherQuestions[].identifier` — the
+     * service rejects unknown ids with `WIRE_SHAPE_ERROR`. Stage 2
+     * (#438) types the array against the recovered SDL shape
+     * `{ answer: string, id: string }` (NOT `questionId` — distinct
+     * from the expertise shape; this field-name asymmetry is per the
+     * recovered SDL).
+     */
+    matcherAnswers?: JobPositionAnswerInput[];
+    /**
+     * Expertise-question answers (`JobExpertiseAnswerInput[]`). Each
+     * entry's `questionId` is validated against
+     * `applyQuestions(jobId).expertiseQuestions[].identifier`. Stage 2
+     * (#438) types the array against the recovered SDL shape
+     * `{ other: string|null, questionId: string, subjectId: string|null }`.
+     */
+    expertiseAnswers?: JobExpertiseAnswerInput[];
+    /**
+     * Pitch input (`PitchInput`). Mapped to the wire's `$talentCard`
+     * variable / `JobApplyInput.pitchData` field. Stage 2 (#438) types
+     * the field against the recovered `PitchInput` shape (`mentorship`
+     * remains `unknown` per ADR-008 spike outcome — the position is
+     * untyped in the SDL).
+     */
+    pitchData?: PitchInput;
+}
+/**
+ * Projected `JobApplication` record returned by {@link apply} on the
+ * apply-success path. Reads the post-mutation `JobApplication` echo
+ * routed through the new activity-item's nested `jobApplication`
+ * field on `TalentJob.activityItem`.
+ *
+ * Shape is the conservative initial projection per #426 AC; #445 live
+ * E2E is the wire authority and may widen the projection if real
+ * responses surface fields the CLI / MCP need to render.
+ */
+export interface JobApplicationRecord {
+    /** `JobApplication.id` — the new application's identifier. */
+    id: string;
+    /** Application status (specific value + verbose label, projected from `TalentJobActivityItem.statusV2`). */
+    statusV2: ApplicationStatus;
+    /**
+     * The rate the wire echoes back on the new `JobApplication`. The
+     * captured op selects `requestedHourlyRate { decimal }` only — no
+     * `verbose` — and the projection mirrors that selection until #445
+     * confirms `verbose` is selectable on this position.
+     */
+    requestedHourlyRate: {
+        decimal: string;
+    } | null;
+    /**
+     * The `TalentJobActivityItem.id` that wraps the new application —
+     * the id callers pass to `applications show` to view the new row.
+     */
+    jobActivityItemId: string;
+}
+/**
+ * Apply-path outcome for {@link apply}. Carries the post-mutation
+ * {@link JobApplicationRecord} projection.
+ */
+export interface JobApplyAppliedOutcome {
+    kind: "applied";
+    result: JobApplicationRecord;
+}
+/**
+ * Dry-run outcome for {@link apply}. Mirrors the
+ * `AvailabilityRequestDryRunPreviewOutcome` pattern from #411 —
+ * named separately for surface symmetry on the apply path.
+ */
+export interface JobApplyDryRunPreviewOutcome {
+    kind: "preview";
+    preview: DryRunPreview;
+}
+/**
+ * Discriminated-union return type for {@link apply}.
+ */
+export type ApplyOutcome = JobApplyAppliedOutcome | JobApplyDryRunPreviewOutcome;
+/**
+ * Direct-apply to a Toptal job — wire `JobApply` (#426, ADR-008
+ * § Decision Part 5).
+ *
+ * Flow:
+ *
+ *   1. **Consent gate**: refuses the call (`CONSENT_REQUIRED`) BEFORE
+ *      any wire call when `input.consentIssued !== true`. Type-system
+ *      gate at `ApplyInput.consentIssued: true` covers compile-time;
+ *      the runtime check covers `as`-cast bypasses and JSON-sourced
+ *      inputs.
+ *   2. **Dry-run short-circuit**: when `options.dryRun === true`,
+ *      emits a {@link DryRunPreview} with the prepared variables
+ *      (including `<resolved at apply time>` placeholders for fields
+ *      that would have been resolved by the pre-fetch) and returns
+ *      `{ kind: "preview", preview }`. Zero wire calls under dry-run —
+ *      including the 3 pre-fetch calls.
+ *   3. **Pre-fetch via Promise.all**: runs `applyData` +
+ *      `applyQuestions` + `rateInsight` concurrently. Promise.all
+ *      rejects-on-first; any pre-fetch failure (NOT_FOUND,
+ *      GRAPHQL_ERROR, AuthRevokedError) blocks the apply.
+ *   4. **Answer validation**: every `matcherAnswers[]` /
+ *      `expertiseAnswers[]` entry's `questionId` must resolve against
+ *      the inventory; unknown ids throw `WIRE_SHAPE_ERROR` with the
+ *      offending array path.
+ *   5. **Rate default**: when `input.requestedHourlyRate` is omitted,
+ *      threads `PreApplyData.suggestedRate` (the talent's own
+ *      configured rate). Throws `MUTATION_ERROR` if neither source
+ *      yields a rate.
+ *   6. **Wire call**: issues `JobApply` against the mobile gateway.
+ *   7. **Error mapping**: a `MutationResult.errors[]` entry with
+ *      `key === "already_applied"` is mapped to `ALREADY_APPLIED`
+ *      with a hint pointing at `ttctl applications show
+ *      <activity-id>`. Other `success: false` responses surface as
+ *      `MUTATION_ERROR` with the formatted error detail.
+ *
+ * **Bad-id behavior**: mutations crash 500 on bad ids per
+ * `project-toptal-wire-quirks` auto-memory. The service does NOT
+ * pre-validate the job id; the pre-fetch suite (`applyData` etc.)
+ * already surfaces NOT_FOUND via the shared widened
+ * {@link NOT_FOUND_MESSAGE_PATTERN} when the bad id is detected
+ * read-side.
+ */
+export declare function apply(token: string, jobId: string, input: ApplyInput, options?: DryRunOptions): Promise<ApplyOutcome>;
+/**
+ * One historical answer to a question similar to the queried one.
+ * Wire selection: `JobPositionAnswer { id answer createdAt }` per the
+ * captured `SimilarJobQuestionAnswers.graphql` operation. `createdAt`
+ * is selected on a schema-gap position (`JobPositionAnswer.createdAt`
+ * is not declared on the synthesized SDL — see the schema-gap note in
+ * the inline query string below); the projection is `string` here per
+ * the empirical wire shape, the T1 snapshot is the authority.
+ */
+export interface SimilarJobAnswer {
+    /** `JobPositionAnswer.id` — the historical answer's identifier. */
+    id: string;
+    /** The historical answer text (`JobPositionAnswer.answer`). */
+    answer: string;
+    /** ISO 8601 timestamp the historical answer was authored. */
+    createdAt: string;
+}
+/**
+ * One group of suggestions, keyed by the question identifier the
+ * suggestions were resolved against. `questionId` mirrors the wire
+ * filter (`forQuestionsSimilarToQuestionId: <questionId>`). The
+ * `suggestions` array carries the talent's own historical answers to
+ * SIMILAR questions on prior applications — useful as autocomplete
+ * candidates the user can review and selectively re-use when authoring
+ * an application.
+ *
+ * Empty `suggestions` arrays surface verbatim: the wire returned zero
+ * similar-job history for this question. Common for new talent
+ * accounts and unique question prompts.
+ */
+export interface SimilarJobAnswerGroup {
+    /**
+     * The `ApplicationQuestion.identifier` (from
+     * {@link ApplicationQuestion}) the suggestions were resolved
+     * against — both matcher and expertise question identifiers are
+     * accepted.
+     */
+    questionId: string;
+    /**
+     * Historical answers to questions semantically similar to the one
+     * identified by `questionId`. Order is server-supplied; the helper
+     * does NOT re-sort.
+     */
+    suggestions: SimilarJobAnswer[];
+}
+/**
+ * Fetch the talent's similar-answer suggestions for every question on
+ * a job's apply form (#452).
+ *
+ * Returns one {@link SimilarJobAnswerGroup} per question — matcher
+ * AND expertise. The order mirrors the underlying
+ * {@link applyQuestions} inventory (matcher questions first, then
+ * expertise; server-supplied order within each section).
+ *
+ * **Cardinality**: N+1 wire calls — first an {@link applyQuestions}
+ * fetch to resolve the question identifier list, then N parallel
+ * `SimilarJobQuestionAnswers` calls (one per question) via
+ * `Promise.all`. The fan-out matches the mobile app's apply-screen
+ * autocomplete behavior; aggregating server-side is not exposed by
+ * the wire.
+ *
+ * **Bad-id behavior**: a bad `jobId` surfaces NOT_FOUND from
+ * `applyQuestions` (same mapping as the rest of the pre-apply suite).
+ * A per-question `SimilarJobQuestionAnswers` call that surfaces
+ * NOT_FOUND propagates verbatim via `Promise.all`'s reject-on-first
+ * — intentional: callers that want graceful per-question fallback
+ * (e.g. the CLI's `--suggest-answers` flag) should catch the rejection
+ * and continue without suggestions.
+ *
+ * **Performance**: when the job has zero questions, the call resolves
+ * to `[]` after the single `applyQuestions` fetch — no wasted parallel
+ * round-trips. When the job has questions but the talent's account
+ * has no similar-job history, each per-question call returns an empty
+ * `suggestions` array; surface the empty grouping verbatim.
+ *
+ * **Off the critical apply path**: this fn is NOT called from
+ * {@link apply}. It's opt-in via the CLI's `--suggest-answers` flag
+ * (#452) and the MCP's `ttctl_jobs_apply_similar_answers` tool. The
+ * design rationale is in the ADR-008 follow-ups thread.
+ *
+ * @param token - Bearer token from the resolved auth config.
+ * @param jobId - The `TalentJob.id` to resolve questions against.
+ * @throws `ApplicationsError("NOT_FOUND")` when the jobId or a
+ *   resolved questionId doesn't resolve.
+ * @throws `ApplicationsError("NO_VIEWER")` for sessions with no
+ *   bound viewer.
+ */
+export declare function similarAnswers(token: string, jobId: string): Promise<SimilarJobAnswerGroup[]>;
+/**
+ * `InterviewStatusEnum` values from the synthesized schema
+ * (`../research/graphql/gateway/schema.graphql`). Closed set.
+ */
+export type InterviewStatus = "ACCEPTED" | "MISSED" | "PENDING" | "REJECTED" | "SCHEDULED" | "TIME_ACCEPTED" | "TIME_REJECTED";
+export declare const INTERVIEW_STATUSES: readonly InterviewStatus[];
+/**
+ * `InterviewKindEnum` values from the synthesized schema. `INTERNAL`
+ * = interview between talent and Toptal (vetting); `EXTERNAL` =
+ * interview between talent and client (post-match).
+ */
+export type InterviewKind = "EXTERNAL" | "INTERNAL";
+/**
+ * `TalentInterviewMethodTypeEnum` values from the synthesized schema.
+ * Typed as a string for forward compatibility with un-enumerated future
+ * members (the wire is untrusted; new method types may appear without
+ * codegen warning).
+ */
+export type InterviewMethodType = string;
+/**
+ * Time-zone descriptor. `value` is the IANA-ish zone name; `location`
+ * is a human-readable label. Either may be `null` when the wire omits
+ * the field.
+ */
+export interface InterviewTimeZone {
+    value: string | null;
+    location: string | null;
+}
+/**
+ * One interviewer-side contact (recruiter, client representative, etc.).
+ * `main: true` flags the primary contact on the interview.
+ */
+export interface InterviewContact {
+    id: string;
+    fullName: string | null;
+    email: string | null;
+    phoneNumber: string | null;
+    position: string | null;
+    main: boolean | null;
+    timeZone: InterviewTimeZone | null;
+}
+/**
+ * Method by which the interview will be conducted (Zoom, phone, etc.).
+ *
+ * - `typeV2` — one of the `TalentInterviewMethodTypeEnum` members
+ *   (`ZOOM`, `PHONE`, `BLUEJEANS`, `CUSTOM_WEB_CONFERENCE`,
+ *   `GOOGLE_HANGOUTS`, `SKYPE`). Stringly-typed because the wire is
+ *   untrusted; the codegen-exclusion may add new members.
+ * - `conferenceUrl` — meeting link for `ZOOM` / `BLUEJEANS` /
+ *   `GOOGLE_HANGOUTS` / `CUSTOM_WEB_CONFERENCE` methods.
+ * - `resource` — free-text channel string (phone number for `PHONE`,
+ *   handle for `SKYPE`).
+ */
+export interface InterviewMethod {
+    typeV2: InterviewMethodType | null;
+    conferenceUrl: string | null;
+    resource: string | null;
+}
+/**
+ * One free-form note the talent has attached to the interview. `section`
+ * is one of the `InterviewGuideSectionIdentifierEnum` members
+ * (`ASK_YOUR_CLIENT`, `GAPS`, `JOB_HIGHLIGHTS`, `POTENTIAL_QUESTIONS`,
+ * `PRO_TIPS`, `STRENGTHS`) or `null` when the note isn't section-pinned.
+ */
+export interface InterviewTalentNote {
+    id: string;
+    section: string | null;
+    note: string | null;
+}
+/**
+ * Back-pointer to the parent job + activity item. Presence indicators
+ * only — the CLI surfaces them as discovery hints (`applications show
+ * <activityId>` to drill into the full activity row).
+ */
+export interface InterviewJobRef {
+    /** `TalentJob.id`. */
+    id: string;
+    /** `TalentJobActivityItem.id` for the activity row containing this interview. */
+    activityItemId: string | null;
+}
+/**
+ * Projected interview detail returned by `interviews.show()`. The shape
+ * the CLI's pretty renderer and the MCP tool's JSON payload depend on.
+ */
+export interface InterviewDetail {
+    id: string;
+    /** `InterviewStatusEnum` member (see {@link INTERVIEW_STATUSES}) or null. */
+    status: InterviewStatus | null;
+    /** `InterviewKindEnum` member or null. */
+    kind: InterviewKind | null;
+    /** Free-text interview-type label (legacy; modern wire prefers {@link kind}). */
+    interviewType: string | null;
+    /** Duration / display string (e.g. `"30 minutes"`). */
+    interviewTime: string | null;
+    /** Recruiter brief, markdown-formatted. */
+    information: string | null;
+    /** Who scheduled the interview (display string). */
+    initiator: string | null;
+    /** Proposed slot timestamps (ISO 8601). */
+    scheduledAtTimes: string[];
+    /** Free-text scheduling comment from the initiator. */
+    schedulingComment: string | null;
+    /** Conference method (Zoom, phone, …) — `null` until the slot is locked. */
+    method: InterviewMethod | null;
+    /** Interviewer contacts. Server-supplied order preserved. */
+    contacts: InterviewContact[];
+    /** Prep-guide id (presence indicator). Full guide is the `InterviewGuide` op, out of scope here. */
+    guideId: string | null;
+    /** Talent's own notes attached to the interview. Server order preserved. */
+    talentNotes: InterviewTalentNote[];
+    /** Back-pointer to the parent job + activity item. */
+    job: InterviewJobRef | null;
+    /** Server-supplied last-mutation timestamp (ISO 8601). */
+    updatedAt: string | null;
+}
+/**
+ * Read one `TalentInterview` by id via the mobile-gateway `Interview`
+ * query (#439). Sibling sub-namespace to the top-level activity-row
+ * leaves (`list` / `show` / `stats`) — fetches the rich interview
+ * detail once the user knows the id from `applications show
+ * <activityId>` (the `Interview: <id>` line).
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` when the id doesn't resolve
+ *   to an interview the signed-in user can see, OR when the wire
+ *   surfaces a `NOT_FOUND_MESSAGE_PATTERN`-matched GraphQL error
+ *   (`Record not found` / `Invalid ID` / Relay `Node id ... resolves to`).
+ * @throws `ApplicationsError("NO_VIEWER")` when the session is valid
+ *   but no viewer is bound.
+ */
+declare function interviewsShow(token: string, id: string): Promise<InterviewDetail>;
+/**
+ * Projected response returned by `interviews.notes.show()`. Shape the
+ * CLI's pretty renderer and the MCP tool's JSON payload depend on.
+ *
+ * `jobId` is the input echo (always populated). `interviewId` /
+ * `interviewKind` are populated when the job has an attached interview;
+ * `null` when the job's `activityItem.interview` is null on the wire
+ * (e.g. the job exists but no interview was scheduled). `notes`
+ * preserves server order; empty array when the interview has no
+ * recorded prep notes.
+ */
+export interface InterviewNotesProjection {
+    jobId: string;
+    interviewId: string | null;
+    interviewKind: InterviewKind | null;
+    notes: InterviewTalentNote[];
+}
+/**
+ * Read the talent's prep notes for the interview attached to a given
+ * job via the portal-side `GetInterviewNotes` query (#440). Sub-sub-
+ * namespace leaf of `applications.interviews.*` — wraps the same
+ * read-only path the portal matcher UI uses to load interview notes.
+ *
+ * @param token   Captured bearer.
+ * @param jobId   `TalentJob.id` (NOT the interview id). Discover via
+ *                `applications interview show <interviewId>` (the
+ *                `Job → Job id` line, populated by the #439 projection)
+ *                or `applications show <activityId>`.
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` when the job id doesn't
+ *   resolve to a job the signed-in user can see, OR when the wire
+ *   surfaces a `NOT_FOUND_MESSAGE_PATTERN`-matched GraphQL error
+ *   (`Record not found` / `Invalid ID` / Relay `Node id ... resolves to`).
+ * @throws `ApplicationsError("NO_VIEWER")` when the session is valid
+ *   but no viewer is bound.
+ */
+declare function interviewsNotesShow(token: string, jobId: string): Promise<InterviewNotesProjection>;
+/**
+ * `InterviewGuideSectionIdentifierEnum` values from the synthesized
+ * schema (`../research/graphql/gateway/schema.graphql`). Closed set —
+ * statically extractable from the schema. The mobile portal uses these
+ * as the prep-guide section spine: `STRENGTHS` (talent's job-match
+ * strengths), `GAPS` (likely follow-up topics), `JOB_HIGHLIGHTS` (key
+ * job characteristics), `POTENTIAL_QUESTIONS` (questions to expect),
+ * `PRO_TIPS` (Toptal interview tips), `ASK_YOUR_CLIENT` (questions to
+ * ask the interviewer).
+ */
+export type InterviewGuideSectionIdentifier = "ASK_YOUR_CLIENT" | "GAPS" | "JOB_HIGHLIGHTS" | "POTENTIAL_QUESTIONS" | "PRO_TIPS" | "STRENGTHS";
+export declare const INTERVIEW_GUIDE_SECTION_IDENTIFIERS: readonly InterviewGuideSectionIdentifier[];
+/**
+ * `InterviewGuideTipIdentifierEnum` values from the synthesized schema
+ * (`../research/graphql/gateway/schema.graphql`). Closed set —
+ * statically extractable from the schema. Each tip identifier is a
+ * named template slot the Toptal guide-rendering pipeline fills with
+ * job/talent-specific content.
+ */
+export type InterviewGuideTipIdentifier = "BE_PRESENTABLE" | "CAMERA_ON" | "DONT_DISCUSS_RATE" | "GAP_ANALYSIS" | "HIRING_FACTORS" | "JOB_SUMMARY" | "PROFILE_REFERENCES" | "QUESTIONS_TO_ASK" | "QUESTIONS_TO_PREPARE_FOR" | "SMALL_TALK" | "STANDARD_QUESTIONS" | "STRENGTHS_OVERLAP";
+export declare const INTERVIEW_GUIDE_TIP_IDENTIFIERS: readonly InterviewGuideTipIdentifier[];
+/**
+ * One tip within an {@link InterviewGuideSection}. `content` is the
+ * job/talent-personalized body (the Toptal guide-rendering pipeline
+ * splices in job-specific examples); `hardcodedContent` is the generic
+ * template body that ships with every guide regardless of job context.
+ * Either or both may be populated; the renderer is responsible for
+ * choosing precedence.
+ */
+export interface InterviewGuideTip {
+    /** `InterviewGuideTipIdentifierEnum` member (see {@link INTERVIEW_GUIDE_TIP_IDENTIFIERS}) or null. */
+    identifier: InterviewGuideTipIdentifier | null;
+    title: string | null;
+    /** Personalized tip body (markdown). May be null when no personalization applies. */
+    content: string | null;
+    /** Generic template body (markdown) shipped with every guide. May be null. */
+    hardcodedContent: string | null;
+}
+/**
+ * One section of the interview-prep guide.
+ */
+export interface InterviewGuideSection {
+    /** `InterviewGuideSectionIdentifierEnum` member (see {@link INTERVIEW_GUIDE_SECTION_IDENTIFIERS}) or null. */
+    identifier: InterviewGuideSectionIdentifier | null;
+    title: string | null;
+    subtitle: string | null;
+    /** Server-supplied order preserved. */
+    tips: InterviewGuideTip[];
+}
+/**
+ * Projected guide payload returned by `interviews.guide.show()`. Shape
+ * the CLI's pretty renderer and the MCP tool's JSON payload depend on.
+ *
+ * `interviewId` is the input echo (always populated). `guideId` /
+ * `sections` are populated when the interview has an attached guide;
+ * `guideId` is `null` and `sections` is `[]` when no guide is attached
+ * to the interview (some interview types may not have a prep guide).
+ */
+export interface InterviewGuideProjection {
+    /** Input echo. */
+    interviewId: string;
+    /** `TalentInterviewGuide.id` — matches `InterviewDetail.guideId` from #439. `null` when no guide is attached. */
+    guideId: string | null;
+    /** Guide sections in server-supplied order. Empty array when no guide is attached. */
+    sections: InterviewGuideSection[];
+}
+/**
+ * Read the interview-prep guide content (sections + tips) for one
+ * interview via the mobile-gateway `InterviewGuide` query (#470).
+ * Sub-sub-namespace leaf of `applications.interviews.*` — wraps the
+ * mobile-portal interview-prep view that talents use to prepare.
+ *
+ * @param token        Captured bearer.
+ * @param interviewId  `TalentInterview.id` (NOT the guide id). Discover
+ *                     via `applications interview show <interviewId>`
+ *                     or `applications show <activityId>`.
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` when the id doesn't resolve
+ *   to an interview the signed-in user can see, OR when the wire
+ *   surfaces a `NOT_FOUND_MESSAGE_PATTERN`-matched GraphQL error
+ *   (`Record not found` / `Invalid ID` / Relay `Node id ... resolves to`).
+ * @throws `ApplicationsError("NO_VIEWER")` when the session is valid
+ *   but no viewer is bound.
+ */
+declare function interviewsGuideShow(token: string, interviewId: string): Promise<InterviewGuideProjection>;
+/**
+ * `applications.interviews.*` sub-namespace. Read-only leaves for
+ * interview-detail access — sibling to the top-level activity-row
+ * leaves on this module. Sub-namespace grouping pattern follows
+ * `payments.rate.*` (#447) and `payments.payouts.*` / `payments.methods.*`
+ * (#149); the plural form here matches `payouts` / `methods` for
+ * collection-style namespaces.
+ *
+ * Sub-sub-namespaces:
+ *   - `interviews.notes.*` (#440) — portal-side notes-focused projection.
+ *     `notes.show(jobId)` is the lightweight read of the talent's prep
+ *     notes for one job's interview, paired with the heavier
+ *     `interviews.show(interviewId)` from #439.
+ *   - `interviews.guide.*` (#470) — mobile-gateway guide-content
+ *     projection. `guide.show(interviewId)` is the read of the
+ *     interview-prep guide (sections + tips). Paired with #439 —
+ *     `interviews.show` surfaces the guide-id presence indicator;
+ *     `interviews.guide.show` fetches the full content.
+ */
+export declare const interviews: {
+    show: typeof interviewsShow;
+    notes: {
+        show: typeof interviewsNotesShow;
+    };
+    guide: {
+        show: typeof interviewsGuideShow;
+    };
+};
+/**
+ * `AvailabilityRequestStatusEnum` values from the synthesized schema
+ * (`../research/graphql/gateway/schema.graphql`). Closed set — unlike
+ * the INFERRED {@link AvailabilityRequestKind} enum, the status enum is
+ * statically extractable from the schema.
+ *
+ * NB: distinct from the GraphQL schema type *named* `AvailabilityRequestStatus`
+ * (the `{ value: String! }` wrapper that `statusV2` / `jirStatus`
+ * resolve to). This TS type is the closed set of `.value` spellings.
+ */
+export type AvailabilityRequestStatus = "CANCELLED" | "CONFIRMED" | "EXPIRED" | "PENDING" | "REJECTED" | "WITHDRAWN";
+export declare const AVAILABILITY_REQUEST_STATUSES: readonly AvailabilityRequestStatus[];
+/**
+ * Projected availability-request detail returned by
+ * `availabilityRequests.show()`. The shape the CLI's pretty renderer
+ * and the MCP tool's JSON payload depend on.
+ */
+export interface AvailabilityRequestDetail {
+    id: string;
+    /**
+     * `AvailabilityRequestStatusEnum` member (see
+     * {@link AVAILABILITY_REQUEST_STATUSES}) or `null`. Read off the
+     * wire's `jirStatus` (aliased `statusV2`) `{ value }` wrapper.
+     */
+    status: AvailabilityRequestStatus | null;
+    /**
+     * AR kind, auto-detected from `metadata.__typename` via
+     * {@link kindFromMetadataTypename}. `null` when metadata is absent or
+     * an unrecognised variant.
+     */
+    kind: AvailabilityRequestKind | null;
+    /**
+     * Recruiter-pinned Fixed hourly rate (the `metadata.offeredHourlyRate`
+     * Money shape). `null` for FLEXIBLE / MARKETPLACE_FLEXIBLE ARs — their
+     * metadata carries no offered rate.
+     */
+    fixedRate: FixedRate | null;
+    /** Recruiter's free-text note attached to the request. */
+    comment: string | null;
+    /** Server-supplied creation timestamp (ISO 8601). */
+    createdAt: string | null;
+    /** Server-supplied last-mutation timestamp (ISO 8601). */
+    updatedAt: string | null;
+    /**
+     * Timestamp the talent answered the request (confirmed / rejected).
+     * `null` while the request is still pending.
+     */
+    answeredAt: string | null;
+    /** The job the availability request is for. */
+    job: ApplicationJobRef | null;
+}
+/**
+ * Read one `AvailabilityRequest` by id via the mobile-gateway
+ * `AvailabilityRequest` query (#442). Sibling sub-namespace to the
+ * top-level activity-row leaves (`list` / `show` / `stats`) and to
+ * `interviews.show` (#439) — fetches the rich availability-request
+ * detail once the user knows the id from `applications show
+ * <activityId>` (the `Availability request: <id>` line). The id is the
+ * same `AvailabilityRequest.id` the #411 `confirm` / `reject` write-side
+ * ops accept.
+ *
+ * @throws `ApplicationsError("NOT_FOUND")` when the id doesn't resolve
+ *   to an availability request the signed-in user can see, OR when the
+ *   wire surfaces a `NOT_FOUND_MESSAGE_PATTERN`-matched GraphQL error
+ *   (`Record not found` / `Invalid ID` / Relay `Node id ... resolves to`).
+ * @throws `ApplicationsError("NO_VIEWER")` when the session is valid
+ *   but no viewer is bound.
+ */
+declare function availabilityRequestsShow(token: string, id: string): Promise<AvailabilityRequestDetail>;
+/**
+ * `applications.availabilityRequests.*` sub-namespace. Read-only leaf
+ * for availability-request-detail access — sibling to `interviews.*`
+ * (#439 / #440) and to the top-level activity-row leaves. The plural
+ * `availabilityRequests` form matches `interviews` / `payouts` /
+ * `methods` for collection-style namespaces; the #411 write-side ops
+ * (`confirm` / `reject` / `rejectReasons`) stay top-level flat exports
+ * (they predate the sub-namespace convention).
+ */
+export declare const availabilityRequests: {
+    show: typeof availabilityRequestsShow;
+};
 //# sourceMappingURL=index.d.ts.map