@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/services/availability/index.js

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { buildDryRunPreview } from "../../transport.js";
+import { callGatewayShared } from "../_shared/transport.js";
+export class AvailabilityError extends Error {
+    code;
+    name = "AvailabilityError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+// ---------------------------------------------------------------------
+// GraphQL operation strings
+//
+// `GetAvailability` is a derived query selecting only the fields
+// `workingHours.show()` / `allocatedHours.show()` / top-level `show()`
+// need.
+//
+// `UpdateWorkingHours` is derived from the captured portal operation;
+// the input shape was recovered from the portal bundle call-site (see
+// module doc comment).
+//
+// `UpdateAllocatedHours` is used VERBATIM from
+// `../research/graphql/gateway/operations/mobile/UpdateAllocatedHours.graphql`.
+// ---------------------------------------------------------------------
+const GET_AVAILABILITY_QUERY = `query GetAvailability {
+  viewer {
+    __typename
+    id
+    viewerRole {
+      __typename
+      allocatedHours
+      timeZone { __typename name value location utcOffset stdOffset }
+      workingTimeFrom
+      workingTimeTo
+      availableShiftRangeFrom
+      availableShiftRangeTo
+      profile { __typename id }
+    }
+  }
+}`;
+const UPDATE_WORKING_HOURS_MUTATION = `mutation UpdateWorkingHours($input: UpdateWorkingHoursInput!) {
+  updateWorkingHours(input: $input) {
+    __typename
+    success
+    notice
+    errors { __typename code key message }
+    profile {
+      __typename
+      id
+      timeZone { __typename name value location utcOffset stdOffset }
+      workingTimeFrom
+      workingTimeTo
+      availableShiftRangeFrom
+      availableShiftRangeTo
+    }
+  }
+}`;
+// Verbatim from `../research/graphql/gateway/operations/mobile/UpdateAllocatedHours.graphql`.
+const UPDATE_ALLOCATED_HOURS_MUTATION = `mutation UpdateAllocatedHours($hours: Int!) { viewerRole { __typename update(input: { allocatedHours: $hours } ) { __typename notice ...mutationResultFields viewer { __typename id ...availabilityData } } } }  fragment mutationResultFields on MutationResult { __typename errors { __typename key message code } success }  fragment lastAllocatedHoursChangeRequestData on AllocatedHoursChangeRequest { __typename id allocatedHours rejectReason comment statusV2 { __typename value } futureAvailableHours returnInDate useReturnAvailability reviewedManually }  fragment availabilityData on Viewer { __typename id preliminarySearchSetting { __typename enabled disablingReason comment } viewerRole { __typename allocatedHours hiredHours lastAllocatedHoursChangeRequest { __typename ...lastAllocatedHoursChangeRequestData } } }`;
+/**
+ * Thin per-service wrapper around {@link callGatewayShared} (issue
+ * #329). Pins the mobile-gateway surface and the
+ * {@link AvailabilityError} domain class.
+ */
+async function callGateway(token, operationName, query, variables, schema) {
+    return callGatewayShared("mobile-gateway", token, operationName, query, variables, AvailabilityError, { schema });
+}
+function formatMutationErrors(prefix, errors) {
+    if (errors == null || errors.length === 0) {
+        return `${prefix}: no error detail returned.`;
+    }
+    const parts = errors.map((e) => {
+        const fields = [];
+        if (e.code != null)
+            fields.push(`code=${e.code}`);
+        if (e.key != null)
+            fields.push(`key=${e.key}`);
+        const head = fields.length > 0 ? `[${fields.join(", ")}] ` : "";
+        return `${head}${e.message ?? "(no message)"}`;
+    });
+    return `${prefix}: ${parts.join("; ")}`;
+}
+/**
+ * Read the signed-in user's full availability snapshot — time zone,
+ * working-hours window, flexible shift range, and allocated hours.
+ *
+ * Throws `AvailabilityError("NO_VIEWER")` when the server returns a
+ * null viewer (defensive — auth-revoked surfaces via `AuthRevokedError`
+ * instead).
+ *
+ * Throws `AvailabilityError("NO_VIEWER_ROLE")` when the viewer exists
+ * but has no role assigned (no role = no working-hours / allocated-hours
+ * shape).
+ */
+export async function show(token) {
+    const data = await callGateway(token, "GetAvailability", GET_AVAILABILITY_QUERY, {});
+    if (data.viewer === null) {
+        throw new AvailabilityError("NO_VIEWER", "Session is valid but no viewer is bound to it.");
+    }
+    if (data.viewer.viewerRole === null) {
+        throw new AvailabilityError("NO_VIEWER_ROLE", "Viewer has no role assigned — no availability data is available. (Are you signed in as a Toptal Talent?)");
+    }
+    const role = data.viewer.viewerRole;
+    return {
+        viewerId: data.viewer.id,
+        profileId: role.profile?.id ?? null,
+        timeZone: role.timeZone,
+        workingTimeFrom: role.workingTimeFrom,
+        workingTimeTo: role.workingTimeTo,
+        availableShiftRangeFrom: role.availableShiftRangeFrom,
+        availableShiftRangeTo: role.availableShiftRangeTo,
+        allocatedHours: role.allocatedHours,
+    };
+}
+/**
+ * Working-hours sub-namespace under the service. Mirrors
+ * `engagements.breaks` so the public surface stays
+ * `availability.workingHours.{show, set}` — matches the CLI verb path
+ * `availability working-hours {show, set}`.
+ */
+export const workingHours = {
+    /**
+     * Read just the working-hours subset of the snapshot. Identical
+     * underlying query to `show()`; the projection here drops
+     * `allocatedHours` for callers that only care about the time-zone
+     * and working-hours fields.
+     */
+    async show(token) {
+        const snap = await show(token);
+        return {
+            viewerId: snap.viewerId,
+            timeZone: snap.timeZone,
+            workingTimeFrom: snap.workingTimeFrom,
+            workingTimeTo: snap.workingTimeTo,
+            availableShiftRangeFrom: snap.availableShiftRangeFrom,
+            availableShiftRangeTo: snap.availableShiftRangeTo,
+        };
+    },
+    /**
+     * Update working-hours fields. All input fields are optional — only
+     * the provided keys are sent in the mutation payload, supporting
+     * partial updates (per portal bundle's call-site behavior).
+     *
+     * Throws `AvailabilityError("MUTATION_ERROR")` when the gateway
+     * returns `success: false` (validation failures, malformed time
+     * strings, unknown time-zone identifiers).
+     *
+     * Returns the post-update working-hours shape wrapped in
+     * {@link WorkingHoursAppliedOutcome}.
+     *
+     * Dry-run path (issue #164): when invoked with `options.dryRun ===
+     * true`, builds a {@link DryRunPreview} of the mutation WITHOUT
+     * invoking the gateway transport — including the `show()` pre-fetch
+     * the apply path uses to resolve `profileId` (per the AC's "no
+     * GraphQL request is sent" requirement). The preview's
+     * `variables.input.profileId` is populated with the placeholder
+     * string `"<resolved at apply time>"`; the wire SHAPE (field names,
+     * operation, surface, redacted headers) is verbatim. Mirrors the
+     * skipped-prefetch pattern from `engagements.breaks.add` (issue #163).
+     */
+    async set(token, input, options = {}) {
+        const profileFields = {};
+        if (input.timeZone !== undefined)
+            profileFields["timeZone"] = input.timeZone;
+        if (input.workingTimeFrom !== undefined)
+            profileFields["workingTimeFrom"] = input.workingTimeFrom;
+        if (input.workingTimeTo !== undefined)
+            profileFields["workingTimeTo"] = input.workingTimeTo;
+        if (input.availableShiftRangeFrom !== undefined)
+            profileFields["availableShiftRangeFrom"] = input.availableShiftRangeFrom;
+        if (input.availableShiftRangeTo !== undefined)
+            profileFields["availableShiftRangeTo"] = input.availableShiftRangeTo;
+        if (Object.keys(profileFields).length === 0) {
+            throw new AvailabilityError("MUTATION_ERROR", "UpdateWorkingHours requires at least one field (timeZone, workingTimeFrom, workingTimeTo, availableShiftRangeFrom, availableShiftRangeTo).");
+        }
+        if (options.dryRun === true) {
+            // Skip the `show()` pre-fetch entirely — the AC mandates zero
+            // transport calls in dry-run mode. The placeholder string stands
+            // in for `profileId` so the preview's `variables.input` matches
+            // the wire shape; the actual id resolves at apply time. Same
+            // pattern as `engagements.breaks.add` (issue #163).
+            return {
+                kind: "preview",
+                preview: buildDryRunPreview({
+                    surface: "mobile-gateway",
+                    authToken: token,
+                    body: {
+                        operationName: "UpdateWorkingHours",
+                        query: UPDATE_WORKING_HOURS_MUTATION,
+                        variables: { input: { profileId: "<resolved at apply time>", profile: profileFields } },
+                    },
+                }),
+            };
+        }
+        // The mutation's `UpdateWorkingHoursInput` requires `profileId: ID!` and
+        // `profile: WorkingHoursInput!` (verified live 2026-05-11 via wire probe
+        // against mobile-gateway — see `.tmp/probe-update-working-hours.mjs`).
+        // Fetch the profile id from the live snapshot so callers don't have to
+        // plumb it through.
+        const snap = await show(token);
+        if (snap.profileId === null) {
+            throw new AvailabilityError("NO_VIEWER_ROLE", "Viewer has a role but no bound profile id — cannot construct UpdateWorkingHours payload.");
+        }
+        const data = await callGateway(token, "UpdateWorkingHours", UPDATE_WORKING_HOURS_MUTATION, { input: { profileId: snap.profileId, profile: profileFields } });
+        if (data.updateWorkingHours === null) {
+            throw new AvailabilityError("UNKNOWN", "UpdateWorkingHours returned a null payload.");
+        }
+        const result = data.updateWorkingHours;
+        if (!result.success) {
+            throw new AvailabilityError("MUTATION_ERROR", formatMutationErrors("UpdateWorkingHours failed", result.errors));
+        }
+        if (result.profile === null) {
+            throw new AvailabilityError("UNKNOWN", "UpdateWorkingHours returned success but the `profile` payload was null.");
+        }
+        return {
+            kind: "applied",
+            result: {
+                timeZone: result.profile.timeZone,
+                workingTimeFrom: result.profile.workingTimeFrom,
+                workingTimeTo: result.profile.workingTimeTo,
+                availableShiftRangeFrom: result.profile.availableShiftRangeFrom,
+                availableShiftRangeTo: result.profile.availableShiftRangeTo,
+                notice: result.notice ?? null,
+            },
+        };
+    },
+};
+/**
+ * Allocated-hours sub-namespace. The wire mutation
+ * (`UpdateAllocatedHours`) operates on `viewerRole`, NOT on a specific
+ * engagement — `allocatedHours` is global across all of the viewer's
+ * active engagements. This is why the surface lives under
+ * `availability` rather than under `engagements` (per #147 scope
+ * amendment that absorbed it into #146).
+ */
+export const allocatedHours = {
+    /**
+     * Read just the allocated-hours value. `hiredHours` is NOT
+     * surfaced here — it's only returned by `set()` (where the
+     * post-update payload includes it for context).
+     */
+    async show(token) {
+        const snap = await show(token);
+        if (snap.allocatedHours === null) {
+            throw new AvailabilityError("UNKNOWN", "Viewer role payload had no allocatedHours field.");
+        }
+        return { allocatedHours: snap.allocatedHours };
+    },
+    /**
+     * Set the viewer-scoped allocated-hours value. The platform UI caps
+     * this at 80 (`SetAvailability` validator); the server enforces the
+     * same range — pass an out-of-range value at your own risk (the
+     * mutation will return `success: false` with a validation error).
+     *
+     * Returns the post-update `{ allocatedHours, hiredHours, notice }`
+     * triple wrapped in {@link AllocatedHoursAppliedOutcome}.
+     *
+     * Dry-run path (issue #164): when invoked with `options.dryRun ===
+     * true`, builds a {@link DryRunPreview} of the mutation without
+     * invoking the gateway transport and returns it wrapped in
+     * {@link AvailabilityDryRunPreviewOutcome}. The integer-range
+     * validation runs BEFORE the dry-run short-circuit — invalid input
+     * still throws `AvailabilityError("MUTATION_ERROR")` rather than
+     * emitting a preview that would be rejected at apply time.
+     */
+    async set(token, hours, options = {}) {
+        if (!Number.isInteger(hours) || hours < 0) {
+            throw new AvailabilityError("MUTATION_ERROR", `UpdateAllocatedHours: hours must be a non-negative integer (got ${String(hours)}).`);
+        }
+        if (options.dryRun === true) {
+            return {
+                kind: "preview",
+                preview: buildDryRunPreview({
+                    surface: "mobile-gateway",
+                    authToken: token,
+                    body: {
+                        operationName: "UpdateAllocatedHours",
+                        query: UPDATE_ALLOCATED_HOURS_MUTATION,
+                        variables: { hours },
+                    },
+                }),
+            };
+        }
+        const data = await callGateway(token, "UpdateAllocatedHours", UPDATE_ALLOCATED_HOURS_MUTATION, { hours });
+        if (data.viewerRole === null) {
+            throw new AvailabilityError("NO_VIEWER_ROLE", "Viewer has no role assigned.");
+        }
+        const result = data.viewerRole.update;
+        if (result === null) {
+            throw new AvailabilityError("UNKNOWN", "UpdateAllocatedHours returned a null payload.");
+        }
+        if (!result.success) {
+            throw new AvailabilityError("MUTATION_ERROR", formatMutationErrors("UpdateAllocatedHours failed", result.errors));
+        }
+        if (result.viewer === null || result.viewer.viewerRole === null) {
+            throw new AvailabilityError("UNKNOWN", "UpdateAllocatedHours returned success but the post-update viewer payload was null.");
+        }
+        return {
+            kind: "applied",
+            result: {
+                allocatedHours: result.viewer.viewerRole.allocatedHours,
+                hiredHours: result.viewer.viewerRole.hiredHours ?? null,
+                notice: result.notice ?? null,
+            },
+        };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/services/availability/index.js.map

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

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

@@ -0,0 +1,132 @@
+/**
+ * Contracts-domain error codes. Mirrors the `EngagementsError` /
+ * `PaymentsError` shape.
+ *
+ * - `NO_TALENT`: HTTP 200 + `data.profile === null` or
+ *   `data.profile.talent === null`. Defensive — the portal usually
+ *   signals an auth-revoked failure differently. A null `talent` would
+ *   indicate a non-talent profile (e.g. a client account) reached this
+ *   surface, which TTCtl's auth model precludes.
+ * - `NOT_FOUND`: `show(id)` was passed a contract-id that doesn't
+ *   appear in `profile.talent.contracts`. Two wire shapes fold here:
+ *   an explicit list that doesn't contain the id, AND a top-level
+ *   GraphQL `Record not found` error (defensive — the portal sometimes
+ *   surfaces unknown-id failures this way for Relay `node(id:)`
+ *   lookups, though `contracts` is a list rather than `node(id:)` so
+ *   the data-shape sentinel is the primary path).
+ * - `GRAPHQL_ERROR`: top-level `errors[]` from the gateway, not an
+ *   auth-revoked extension and not a `Record not found`.
+ * - `NETWORK_ERROR`, `UNKNOWN`: standard transport failure modes.
+ *
+ * Auth-revoked failures throw `AuthRevokedError` (cross-cutting
+ * `TtctlError` subclass per #77), not a code on this enum. `ProfileError`
+ * from `extractProfileId(token)` (the profileId-resolution round-trip)
+ * also propagates verbatim — a profile-read failure surfaces with the
+ * same actionable message as `ttctl profile show`.
+ */
+export type ContractsErrorCode = "NO_TALENT" | "NO_VIEWER" | "NOT_FOUND" | "GRAPHQL_ERROR" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR" | "UNKNOWN";
+export declare class ContractsError extends Error {
+    readonly code: ContractsErrorCode;
+    readonly name = "ContractsError";
+    constructor(code: ContractsErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A talent-level legal document — Toptal Direct, Master Service
+ * Agreement, etc. Projected from the `Contract` type at
+ * `../research/graphql/talent_profile/schema.graphql:163`. Every field
+ * is `Unknown`-typed in the synthesized SDL, so the runtime types here
+ * are best-effort INFERRED until the gated E2E test pins them.
+ *
+ * Semantics (best-effort, pending E2E confirmation):
+ *
+ *   - `id`: Relay-style addressable id (string).
+ *   - `kind`: contract kind enum value (e.g. `"TOPTAL_DIRECT"`,
+ *     `"MASTER_SERVICE_AGREEMENT"`). Surfaced as `string` to remain
+ *     forward-compatible with new enum values.
+ *   - `provider`: contract provider/source (e.g. `"TOPTAL"`, a client
+ *     name). String for forward-compat.
+ *   - `status`: contract lifecycle status (e.g. `"SIGNED"`, `"PENDING"`,
+ *     `"DRAFT"`). String for forward-compat.
+ *   - `billingType`: billing arrangement (e.g. `"HOURLY"`, `"FIXED"`).
+ *     Nullable in case some contract kinds (MSAs) carry no billing-type
+ *     binding.
+ *   - `signedAt`: ISO-8601 timestamp when the talent signed. Null when
+ *     not yet signed.
+ *   - `sentAt`: ISO-8601 timestamp when Toptal sent the document. Null
+ *     when not yet sent.
+ *   - `isActive`: boolean indicating active/binding state. Null shape
+ *     allowed defensively.
+ *   - `verificationDeadline`: ISO-8601 timestamp by which the talent
+ *     must complete verification steps. Null when no deadline applies.
+ *   - `title`: human-readable contract title. Null shape allowed
+ *     defensively.
+ *
+ * Nullability is conservative — the SDL has `Unknown` placeholders
+ * which carry no nullability signal. The CLI / MCP rendering layer
+ * handles `null` defensively. Once the E2E run pins real types, tighten
+ * the nullability here if observation supports it.
+ */
+export interface Contract {
+    id: string;
+    kind: string | null;
+    provider: string | null;
+    status: string | null;
+    billingType: string | null;
+    signedAt: string | null;
+    sentAt: string | null;
+    isActive: boolean | null;
+    verificationDeadline: string | null;
+    title: string | null;
+}
+/**
+ * List the talent's top-level legal contracts via
+ * `profile(id:).talent.contracts` on the portal surface.
+ *
+ * Two round-trips: first a mobile-gateway `profile.basic.show()` call
+ * via `extractProfileId(token)` to resolve the user's `profileId`, then
+ * the `GetContracts` query against `talent-profile/graphql` with the
+ * resolved id.
+ *
+ * Returns the contracts in server order (no client-side sort). An
+ * empty list is a legitimate return value (a talent who hasn't signed
+ * any contract yet); callers MUST handle the empty case explicitly.
+ *
+ * Throws (typed):
+ *
+ *   - `AuthRevokedError` — session bearer is invalid or expired.
+ *   - `Cf403Error` (from the transport) — Cloudflare blocked the
+ *     request despite Chrome TLS impersonation; the CLI/MCP surfaces
+ *     render the verbatim guidance to file an issue.
+ *   - `ProfileError` — the `extractProfileId(token)` round-trip
+ *     failed (e.g. the viewer payload had no `viewerRole.profileId`).
+ *     Propagates verbatim so the user sees the same actionable message
+ *     as `ttctl profile show`.
+ *   - `ContractsError(NO_TALENT)` — `data.profile` or
+ *     `data.profile.talent` is null (defensive; auth failures usually
+ *     surface through `AuthRevokedError`).
+ *   - `ContractsError(GRAPHQL_ERROR)` — top-level GraphQL error, not
+ *     auth-revoked, not a `Record not found`.
+ *   - `ContractsError(NETWORK_ERROR)` — transport failure (DNS, TLS,
+ *     connection reset).
+ *   - `ContractsError(UNKNOWN)` — non-2xx HTTP status or missing
+ *     `data` field.
+ */
+export declare function list(token: string): Promise<Contract[]>;
+/**
+ * Show a single contract by id. The portal surface does not expose a
+ * `contract(id:)` lookup — `show()` fetches the full
+ * `profile(id:).talent.contracts` list and filters client-side. The
+ * round-trip cost is the same as `list()`; latency-conscious callers
+ * may prefer `list()` + their own filter when retrieving multiple
+ * contracts.
+ *
+ * Throws:
+ *
+ *   - everything `list()` throws, plus
+ *   - `ContractsError(NOT_FOUND)` — no contract with the supplied id
+ *     was found in `profile.talent.contracts`.
+ */
+export declare function show(token: string, id: string): Promise<Contract>;
+//# sourceMappingURL=index.d.ts.map

package/dist/services/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/contracts/index.ts"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,SAAS,CAAC;AAEd,qBAAa,cAAe,SAAQ,KAAK;aAGrB,IAAI,EAAE,kBAAkB;IAF1C,SAAkB,IAAI,oBAAoB;gBAExB,IAAI,EAAE,kBAAkB,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAoKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAqC7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOvE"}

package/dist/services/contracts/index.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { callGatewayShared } from "../_shared/transport.js";
+import { extractProfileId } from "../profile/shared.js";
+export class ContractsError extends Error {
+    code;
+    name = "ContractsError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+// ---------------------------------------------------------------------
+// GraphQL operation (hand-authored)
+// ---------------------------------------------------------------------
+// Hand-authored — modeled on the captured
+// `research/graphql/talent_profile/operations/getLegalSettingsData.graphql`,
+// which is the canonical wire path the portal SPA uses to read the
+// talent's contracts (`profile(id:).talent.contracts`). Two other
+// candidates were rejected by the live API in pre-merge E2E validation:
+//
+//   - `viewer.contracts` (the capture at
+//     `research/graphql/gateway/operations/portal/GetContracts.graphql`):
+//     `Field 'contracts' doesn't exist on type 'Viewer'`. The `Viewer`
+//     SDL declaration of `contracts: Contract` (line 671 of
+//     `talent_profile/schema.graphql`) is the schema synthesizer's
+//     hypothesis that was never verified by a capture.
+//   - `activation.talent.contracts` (from the captured
+//     `GetActivationLegalData` op): `Field 'activation' doesn't exist
+//     on type 'Query'`. The SDL declares `Query.activation: Unknown`
+//     but the live talent_profile endpoint rejects it — likely a
+//     non-activated-talent path that only works in specific account
+//     states.
+//
+// `profile(id: $profileId)` is the universally-accessible path. The
+// `profileId` is resolved via `extractProfileId(token)` which does
+// one mobile-gateway round-trip to `profile.basic.show()` to read
+// `viewerRole.profileId`. The two-round-trip cost matches `payments`
+// service patterns.
+//
+// Operation name kept as `GetContracts` so any future server-side
+// allow-listing keyed on operation name continues to recognize it.
+//
+// Projection is the 10-field full shape from
+// `talent_profile/fragments/Contract.graphql`. Every field is
+// `Unknown`-typed in the synthesized SDL → INFERRED.
+const GET_CONTRACTS_QUERY = `query GetContracts($profileId: ID!) {
+  profile(id: $profileId) {
+    __typename
+    id
+    talent {
+      __typename
+      id
+      contracts {
+        __typename
+        id
+        kind
+        provider
+        status
+        billingType
+        signedAt
+        sentAt
+        isActive
+        verificationDeadline
+        title
+      }
+    }
+  }
+}`;
+// Defensive remap: if the portal surface ever returns a `Record not
+// found`-style top-level GraphQL error for an unknown contract id (the
+// gateway convention for Relay `node(id:)` lookups), fold it into the
+// typed `NOT_FOUND` code. The primary `show()` path filters
+// client-side; this is belt-and-braces for any future server-side
+// `viewer.contract(id:)` lookup.
+const NOT_FOUND_MESSAGE_PATTERN = /Record not found/i;
+// ---------------------------------------------------------------------
+// Transport helper
+// ---------------------------------------------------------------------
+/**
+ * Thin per-service wrapper around {@link callGatewayShared} (issue
+ * #329). Pins the talent-profile surface and the {@link ContractsError}
+ * domain class.
+ *
+ * The `Record not found` → `NOT_FOUND` remap previously lived inside
+ * the local helper. It's now applied at the {@link list} call site via
+ * a `GRAPHQL_ERROR` → `NOT_FOUND` translation (matching the pattern
+ * used in `applications.show()`, `jobs.show()`, `timesheet.resolve()`).
+ * The remap is defensive — the primary `show()` path filters
+ * client-side, but the gateway might surface `Record not found` as a
+ * top-level GraphQL error if a future `viewer.contract(id:)` lookup
+ * ever lands.
+ */
+async function callTalentProfile(token, operationName, query, variables, schema) {
+    return callGatewayShared("talent-profile", token, operationName, query, variables, ContractsError, { schema });
+}
+// ---------------------------------------------------------------------
+// Projection
+// ---------------------------------------------------------------------
+function projectContract(wire) {
+    return {
+        id: wire.id,
+        kind: wire.kind,
+        provider: wire.provider,
+        status: wire.status,
+        billingType: wire.billingType,
+        signedAt: wire.signedAt,
+        sentAt: wire.sentAt,
+        isActive: wire.isActive,
+        verificationDeadline: wire.verificationDeadline,
+        title: wire.title,
+    };
+}
+// ---------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------
+/**
+ * List the talent's top-level legal contracts via
+ * `profile(id:).talent.contracts` on the portal surface.
+ *
+ * Two round-trips: first a mobile-gateway `profile.basic.show()` call
+ * via `extractProfileId(token)` to resolve the user's `profileId`, then
+ * the `GetContracts` query against `talent-profile/graphql` with the
+ * resolved id.
+ *
+ * Returns the contracts in server order (no client-side sort). An
+ * empty list is a legitimate return value (a talent who hasn't signed
+ * any contract yet); callers MUST handle the empty case explicitly.
+ *
+ * Throws (typed):
+ *
+ *   - `AuthRevokedError` — session bearer is invalid or expired.
+ *   - `Cf403Error` (from the transport) — Cloudflare blocked the
+ *     request despite Chrome TLS impersonation; the CLI/MCP surfaces
+ *     render the verbatim guidance to file an issue.
+ *   - `ProfileError` — the `extractProfileId(token)` round-trip
+ *     failed (e.g. the viewer payload had no `viewerRole.profileId`).
+ *     Propagates verbatim so the user sees the same actionable message
+ *     as `ttctl profile show`.
+ *   - `ContractsError(NO_TALENT)` — `data.profile` or
+ *     `data.profile.talent` is null (defensive; auth failures usually
+ *     surface through `AuthRevokedError`).
+ *   - `ContractsError(GRAPHQL_ERROR)` — top-level GraphQL error, not
+ *     auth-revoked, not a `Record not found`.
+ *   - `ContractsError(NETWORK_ERROR)` — transport failure (DNS, TLS,
+ *     connection reset).
+ *   - `ContractsError(UNKNOWN)` — non-2xx HTTP status or missing
+ *     `data` field.
+ */
+export async function list(token) {
+    const profileId = await extractProfileId(token);
+    let data;
+    try {
+        data = await callTalentProfile(token, "GetContracts", GET_CONTRACTS_QUERY, {
+            profileId,
+        });
+    }
+    catch (err) {
+        // Defensive: if the portal surface ever switches to returning
+        // `Record not found` as a top-level GraphQL error for the
+        // contracts list (e.g. through a `viewer.contract(id:)` lookup
+        // path), surface it as the typed `NOT_FOUND` code instead of the
+        // generic `GRAPHQL_ERROR`. Matches the pattern used in
+        // `applications.show()` / `jobs.show()` / `timesheet.resolve()`.
+        //
+        // The wire-level GraphQL message is lifted off `err.cause` (set
+        // by `callGatewayShared` to the offending `GraphQLErrorEntry`) so
+        // the user-facing message stays "Contract not found: <wire-reason>"
+        // — without the `${operationName} failed:` prefix that lives in
+        // `err.message`.
+        if (err instanceof ContractsError && err.code === "GRAPHQL_ERROR" && NOT_FOUND_MESSAGE_PATTERN.test(err.message)) {
+            const wireMessage = err.cause?.message ?? "Record not found";
+            throw new ContractsError("NOT_FOUND", `Contract not found: ${wireMessage}`, { cause: err });
+        }
+        throw err;
+    }
+    if (data === null || data === undefined) {
+        throw new ContractsError("UNKNOWN", "GetContracts returned no `data` payload.");
+    }
+    if (data.profile === null) {
+        throw new ContractsError("NO_TALENT", "GetContracts response had `profile: null`.");
+    }
+    if (data.profile.talent === null) {
+        throw new ContractsError("NO_TALENT", "GetContracts response had `profile.talent: null`.");
+    }
+    const wire = data.profile.talent.contracts ?? [];
+    return wire.map(projectContract);
+}
+/**
+ * Show a single contract by id. The portal surface does not expose a
+ * `contract(id:)` lookup — `show()` fetches the full
+ * `profile(id:).talent.contracts` list and filters client-side. The
+ * round-trip cost is the same as `list()`; latency-conscious callers
+ * may prefer `list()` + their own filter when retrieving multiple
+ * contracts.
+ *
+ * Throws:
+ *
+ *   - everything `list()` throws, plus
+ *   - `ContractsError(NOT_FOUND)` — no contract with the supplied id
+ *     was found in `profile.talent.contracts`.
+ */
+export async function show(token, id) {
+    const items = await list(token);
+    const match = items.find((c) => c.id === id);
+    if (match === undefined) {
+        throw new ContractsError("NOT_FOUND", `No contract found with id "${id}" (or you don't have access to it).`);
+    }
+    return match;
+}
+//# sourceMappingURL=index.js.map