@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/services/_shared/transport.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Shared GraphQL transport wrapper for service modules (issue #329).
+ *
+ * Replaces 8 near-identical `callGateway` / `callTalentProfile`
+ * helpers that previously lived inside individual service files
+ * (`services/{applications,availability,contracts,engagements,jobs,
+ * payments,profile/skills,timesheet}`). The Zod-validation hook
+ * (`buildWireShapeError`, Z-3 / #286) used to be duplicated across 9
+ * sites; here it lives once.
+ *
+ * The per-service helpers all shared a common envelope but differed in
+ * three bounded ways:
+ *
+ *   1. **Surface**: mobile-gateway (via `stockTransport`) or
+ *      talent-profile (via `impersonatedTransport`). Resolved here by
+ *      delegating to `callSurface`, which dispatches based on
+ *      `SURFACES_REQUIRING_IMPERSONATION`.
+ *   2. **Domain error class**: each service threw its own typed error
+ *      (`ApplicationsError`, `JobsError`, …) so callers can pattern-
+ *      match `instanceof ServiceError && err.code === "GRAPHQL_ERROR"`
+ *      without importing a cross-domain enum. We accept the class
+ *      itself via the `errorFactory` parameter and instantiate it
+ *      with the code strings every existing helper already used.
+ *   3. **Viewer-binding check**: `applications` requires that the
+ *      response include a non-null `viewer` (the gateway treats a
+ *      missing viewer as "session valid but no viewer bound", which
+ *      should surface as `NO_VIEWER` rather than a generic error). All
+ *      other services omit this check. Toggled via
+ *      `opts.requireViewer`.
+ *
+ * `profile/shared.ts#callTalentProfile` remains a separate helper for
+ * the moment because its signature differs (it returns the raw
+ * `TransportResponse`, takes a `verb` parameter for error tagging, and
+ * defers top-level error handling to `ensureNoTopLevelErrors`). The 4
+ * profile sub-domains (`industries`, `education`, `employment`,
+ * `certifications`) consume it, so a separate migration will handle
+ * that consolidation — see #329 follow-up.
+ *
+ * @see {@link callGatewayShared}
+ */
+import type { z } from "zod";
+import type { ToptalSurface } from "../../types.js";
+/**
+ * Codes that {@link callGatewayShared} may throw via its
+ * {@link DomainErrorFactory}. Every consuming service's per-domain
+ * error code union (e.g. `ApplicationsErrorCode`, `JobsErrorCode`)
+ * must be a superset of this set (plus its own domain-specific
+ * extensions like `NOT_FOUND`).
+ *
+ * `NO_VIEWER` is included unconditionally even though only callers
+ * passing `opts.requireViewer: true` will see it — services that
+ * don't opt into the viewer check still need their factory's code
+ * union to permit it for the parameter type to satisfy the factory
+ * signature. The runtime never throws `NO_VIEWER` for these services.
+ */
+export type SharedTransportErrorCode = "NETWORK_ERROR" | "GRAPHQL_ERROR" | "WIRE_SHAPE_ERROR" | "NO_VIEWER" | "UNKNOWN";
+/**
+ * Constructor signature for any domain-error class consumed by
+ * {@link callGatewayShared}.
+ *
+ * The `code` parameter is typed as {@link SharedTransportErrorCode}.
+ * Each consuming service's domain error code union
+ * (e.g. `ApplicationsErrorCode`, `JobsErrorCode`) must be a
+ * **superset** of {@link SharedTransportErrorCode} — i.e., every
+ * shared code is one of the domain's accepted code strings. Under
+ * TypeScript's constructor-parameter contravariance, a class whose
+ * constructor accepts a wider code union (e.g.
+ * `ApplicationsErrorCode = "NO_VIEWER" | "NOT_FOUND" | …shared codes`)
+ * satisfies `new (code: SharedTransportErrorCode, …) => ApplicationsError`.
+ *
+ * This is verified at compile time at every `callGatewayShared` call
+ * site: passing a domain error class whose code union is missing a
+ * shared code (e.g. lacks `NO_VIEWER`) raises an assignment error.
+ */
+export interface DomainErrorFactory<E extends Error> {
+    new (code: SharedTransportErrorCode, message: string, options?: {
+        cause?: unknown;
+    }): E;
+}
+/**
+ * Optional knobs for {@link callGatewayShared}.
+ */
+export interface CallGatewaySharedOptions<T> {
+    /**
+     * Zod schema applied to `body.data` before returning. On parse
+     * failure the helper throws `errorFactory("WIRE_SHAPE_ERROR", …)`
+     * with the original {@link z.ZodError} chained via `cause` and a
+     * field-level diff in the message per
+     * `docs/wire-validation-error-format.md` (Z-3 / #286). When
+     * omitted, the existing pass-through behavior is preserved.
+     *
+     * `| undefined` accommodates `exactOptionalPropertyTypes` — per-
+     * service wrappers thread their own `schema?: z.ZodType<T>`
+     * parameter through unchanged (which may be `undefined`).
+     */
+    schema?: z.ZodType<T> | undefined;
+    /**
+     * When `true`, the helper additionally narrows `data` to
+     * `{ viewer: { id: string } | null }` and throws
+     * `errorFactory("NO_VIEWER", …)` if `data.viewer === null`. Used
+     * by `applications` (the gateway returns `viewer === null` when
+     * the session is technically valid but no viewer is bound — e.g.
+     * the bearer maps to a non-talent account). Other services either
+     * use schemas that already constrain `viewer` or don't carry a
+     * `viewer` field in their wire shape.
+     */
+    requireViewer?: boolean | undefined;
+}
+/**
+ * Fire a GraphQL request against a Toptal surface and turn
+ * transport-level outcomes into a typed domain error.
+ *
+ * Surface routing: {@link impersonatedTransport} for surfaces in
+ * {@link SURFACES_REQUIRING_IMPERSONATION} (talent-profile,
+ * scheduler), {@link stockTransport} otherwise (mobile-gateway).
+ * Routing is inlined here rather than delegating to `callSurface`
+ * because existing service-level tests mock these transport
+ * functions directly via `vi.mock("../../transport.js", …)`;
+ * routing through `callSurface` would bypass those mocks
+ * (the function captures a closure reference at module-load time).
+ *
+ * Error mapping:
+ * - {@link TtctlError} subclasses ({@link AuthRevokedError},
+ *   `Cf403Error`, etc.) propagate as-is so the CLI / MCP surfaces
+ *   apply uniform `recovery` rendering.
+ * - Other transport throws → `errorFactory("NETWORK_ERROR", …)`.
+ * - HTTP 401 → {@link AuthRevokedError}.
+ * - Non-2xx → `errorFactory("UNKNOWN", …)`.
+ * - Top-level `errors[]` with an auth-revoked extension code (per
+ *   {@link isAuthRevokedExtensionCode}) → {@link AuthRevokedError}.
+ * - Top-level `errors[]` otherwise → `errorFactory("GRAPHQL_ERROR", …)`
+ *   with the offending {@link GraphQLErrorEntry} chained via `cause`
+ *   (callers that remap to a domain-specific code — e.g. contracts
+ *   translating `Record not found` to `NOT_FOUND` — can lift the wire
+ *   message off `err.cause.message` without parsing `err.message`).
+ * - Missing `data` field → `errorFactory("UNKNOWN", …)`.
+ * - Zod parse failure (when `schema` provided) →
+ *   `errorFactory("WIRE_SHAPE_ERROR", …)` carrying the diff payload.
+ * - `data.viewer === null` (when `requireViewer` true) →
+ *   `errorFactory("NO_VIEWER", …)`.
+ *
+ * Returns the validated `body.data` narrowed to `T`. When `schema` is
+ * omitted, the cast is unverified — callers should provide a schema
+ * for any operation whose wire shape is gappy in the synthesized SDL
+ * (CLAUDE.md § Track 1 vs Track 2 disposition).
+ */
+export declare function callGatewayShared<T, E extends Error>(surface: ToptalSurface, token: string, operationName: string, query: string, variables: Record<string, unknown>, errorFactory: DomainErrorFactory<E>, opts?: CallGatewaySharedOptions<T>): Promise<T>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/services/_shared/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/services/_shared/transport.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAO7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,eAAe,GAAG,kBAAkB,GAAG,WAAW,GAAG,SAAS,CAAC;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,KAAK;IACjD,KAAK,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,CAAC,CAAC;CACzF;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAClC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,EACxD,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,YAAY,EAAE,kBAAkB,CAAC,CAAC,CAAC,EACnC,IAAI,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,CAAC,CAAC,CAyDZ"}

package/dist/services/_shared/transport.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { AuthRevokedError, TtctlError } from "../../auth/errors.js";
+import { buildWireShapeError } from "../../lib/wire-shape.js";
+import { impersonatedTransport, stockTransport } from "../../transport.js";
+import { SURFACES_REQUIRING_IMPERSONATION } from "../../types.js";
+import { isAuthRevokedExtensionCode } from "../profile/shared.js";
+/**
+ * Fire a GraphQL request against a Toptal surface and turn
+ * transport-level outcomes into a typed domain error.
+ *
+ * Surface routing: {@link impersonatedTransport} for surfaces in
+ * {@link SURFACES_REQUIRING_IMPERSONATION} (talent-profile,
+ * scheduler), {@link stockTransport} otherwise (mobile-gateway).
+ * Routing is inlined here rather than delegating to `callSurface`
+ * because existing service-level tests mock these transport
+ * functions directly via `vi.mock("../../transport.js", …)`;
+ * routing through `callSurface` would bypass those mocks
+ * (the function captures a closure reference at module-load time).
+ *
+ * Error mapping:
+ * - {@link TtctlError} subclasses ({@link AuthRevokedError},
+ *   `Cf403Error`, etc.) propagate as-is so the CLI / MCP surfaces
+ *   apply uniform `recovery` rendering.
+ * - Other transport throws → `errorFactory("NETWORK_ERROR", …)`.
+ * - HTTP 401 → {@link AuthRevokedError}.
+ * - Non-2xx → `errorFactory("UNKNOWN", …)`.
+ * - Top-level `errors[]` with an auth-revoked extension code (per
+ *   {@link isAuthRevokedExtensionCode}) → {@link AuthRevokedError}.
+ * - Top-level `errors[]` otherwise → `errorFactory("GRAPHQL_ERROR", …)`
+ *   with the offending {@link GraphQLErrorEntry} chained via `cause`
+ *   (callers that remap to a domain-specific code — e.g. contracts
+ *   translating `Record not found` to `NOT_FOUND` — can lift the wire
+ *   message off `err.cause.message` without parsing `err.message`).
+ * - Missing `data` field → `errorFactory("UNKNOWN", …)`.
+ * - Zod parse failure (when `schema` provided) →
+ *   `errorFactory("WIRE_SHAPE_ERROR", …)` carrying the diff payload.
+ * - `data.viewer === null` (when `requireViewer` true) →
+ *   `errorFactory("NO_VIEWER", …)`.
+ *
+ * Returns the validated `body.data` narrowed to `T`. When `schema` is
+ * omitted, the cast is unverified — callers should provide a schema
+ * for any operation whose wire shape is gappy in the synthesized SDL
+ * (CLAUDE.md § Track 1 vs Track 2 disposition).
+ */
+export async function callGatewayShared(surface, token, operationName, query, variables, errorFactory, opts) {
+    const transport = SURFACES_REQUIRING_IMPERSONATION.has(surface) ? impersonatedTransport : stockTransport;
+    let res;
+    try {
+        res = await transport({
+            surface,
+            authToken: token,
+            body: { operationName, query, variables },
+        });
+    }
+    catch (err) {
+        if (err instanceof TtctlError)
+            throw err;
+        throw new errorFactory("NETWORK_ERROR", `${operationName} request failed: ${err.message}`, {
+            cause: err,
+        });
+    }
+    if (res.status === 401) {
+        throw new AuthRevokedError("Session is invalid or expired.");
+    }
+    if (res.status < 200 || res.status >= 300) {
+        throw new errorFactory("UNKNOWN", `${operationName} returned HTTP ${res.status.toString()}`);
+    }
+    const body = res.body;
+    if (body && Array.isArray(body.errors) && body.errors.length > 0) {
+        const first = body.errors[0];
+        if (isAuthRevokedExtensionCode(first?.extensions?.code)) {
+            throw new AuthRevokedError("Session is invalid or expired.");
+        }
+        throw new errorFactory("GRAPHQL_ERROR", `${operationName} failed: ${first?.message ?? "GraphQL error"}`, {
+            cause: first,
+        });
+    }
+    if (!body?.data) {
+        throw new errorFactory("UNKNOWN", `${operationName} response had no \`data\` field`);
+    }
+    let data;
+    if (opts?.schema !== undefined) {
+        const parsed = opts.schema.safeParse(body.data);
+        if (!parsed.success) {
+            const payload = buildWireShapeError(operationName, parsed.error, body.data);
+            throw new errorFactory("WIRE_SHAPE_ERROR", payload.message, { cause: parsed.error });
+        }
+        data = parsed.data;
+    }
+    else {
+        data = body.data;
+    }
+    if (opts?.requireViewer === true) {
+        const withViewer = data;
+        if (withViewer.viewer === null) {
+            throw new errorFactory("NO_VIEWER", "Session is valid but no viewer is bound to it.");
+        }
+    }
+    return data;
+}
+//# sourceMappingURL=transport.js.map

package/dist/services/_shared/transport.js.map

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

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

@@ -0,0 +1,210 @@
+/**
+ * Applications-domain error codes. Mirrors the `ProfileError` /
+ * `SkillsError` shape per project convention so each sub-domain carries
+ * its own typed error class without callers having to import a shared
+ * cross-domain enum. Auth-revoked failures throw `AuthRevokedError`
+ * (cross-cutting `TtctlError` subclass per #77), not a code on this
+ * enum.
+ *
+ * `NOT_FOUND` is specific to `show()`: the gateway returns a successful
+ * response with `viewer.jobActivityItem === null` when the supplied id
+ * doesn't resolve to an item the signed-in user can see (no separate
+ * 404 status). The service translates that explicit null to a typed
+ * `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" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR" | "UNKNOWN";
+export declare class ApplicationsError extends Error {
+    readonly code: ApplicationsErrorCode;
+    readonly name = "ApplicationsError";
+    constructor(code: ApplicationsErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The five known values of `JobActivityItemStatusGroupEnum` from the
+ * synthesized schema (`../research/graphql/gateway/schema.graphql`
+ * line 176). Re-declared here as a literal-typed tuple so consumers
+ * (CLI flag validation, MCP `z.enum`, `stats()` iteration) share one
+ * source of truth without depending on the codegen output.
+ *
+ * Order matches the schema declaration. `stats()` iterates this array
+ * to issue one count call per group.
+ */
+export declare const STATUS_GROUPS: readonly ["ACTIVE_ENGAGEMENT", "ARCHIVED", "CLOSED_ENGAGEMENT", "ON_CLIENT_REVIEW", "ON_RECRUITER_REVIEW"];
+export type StatusGroup = (typeof STATUS_GROUPS)[number];
+/**
+ * Optional list filter — both fields fold straight into the captured
+ * operation's variables (`keywords`, `onlyStatusGroupFilter`).
+ */
+export interface ListOptions {
+    /**
+     * Free-text keyword filter. Each entry is matched server-side against
+     * job title, client name, and other indexed fields. Multiple keywords
+     * AND together (per observed behavior in the mobile app).
+     */
+    keywords?: string[];
+    /**
+     * Restrict the list to one or more status groups. When omitted the
+     * server returns rows from every group.
+     */
+    statusGroups?: StatusGroup[];
+}
+/**
+ * Status payload — both `statusV2` (specific) and `statusGroupV2`
+ * (coarse, one of {@link STATUS_GROUPS}) carry the same shape on the
+ * wire. `verbose` is the human-readable label the Toptal UI shows
+ * (e.g. "Active Engagement", "Archived").
+ */
+export interface ApplicationStatus {
+    value: string;
+    verbose: string;
+}
+/**
+ * Reference to a job an activity row points at. The full `TalentJob`
+ * type carries 30+ fields; this projection surfaces only what `list` /
+ * `show` render. `client.fullName` is the company name as the user
+ * sees it.
+ */
+export interface ApplicationJobRef {
+    id: string;
+    title: string | null;
+    url: string | null;
+    client: {
+        id: string;
+        fullName: string | null;
+    } | null;
+}
+/**
+ * One row in the activity list — the CLI's `applications list` and the
+ * MCP's `ttctl_applications_list` both surface this shape. `engagement`,
+ * `jobApplication`, `availabilityRequest`, and `interview` are all
+ * presence indicators (only `id` is selected) — a non-null value tells
+ * the consumer "this row has reached the corresponding lifecycle
+ * stage". The `mostRelevantApplication` union from the captured
+ * operation is intentionally elided here: it duplicates information
+ * `jobApplication` / `availabilityRequest` already carry.
+ */
+export interface JobActivityItem {
+    id: string;
+    statusV2: ApplicationStatus;
+    statusGroupV2: ApplicationStatus;
+    statusColor: string | null;
+    lastUpdatedAt: string;
+    job: ApplicationJobRef;
+    jobApplication: {
+        id: string;
+    } | null;
+    engagement: {
+        id: string;
+    } | null;
+    availabilityRequest: {
+        id: string;
+    } | null;
+    interview: {
+        id: string;
+    } | null;
+}
+/**
+ * Detail-view shape for `applications show <id>`. Extends
+ * {@link JobActivityItem} with extra job metadata (description, work
+ * type, dates) and engagement / application detail fields (rate,
+ * commitment, current billing cycle).
+ *
+ * Field selection is deliberately conservative — the captured
+ * `JobActivityItem` operation pulls in the full `jobData` +
+ * `jobActivityEngagementData` fragments (~50 fields). The shape here
+ * picks the fields the CLI's `pretty` formatter actually renders;
+ * future expansions can additively widen the projection.
+ */
+export interface JobActivityItemDetail extends JobActivityItem {
+    job: ApplicationJobRef & {
+        descriptionMd: string | null;
+        expectedHours: number | null;
+        commitment: {
+            slug: string;
+        } | null;
+        workType: {
+            slug: string;
+        } | null;
+        specialization: {
+            title: string;
+        } | null;
+        startDate: string | null;
+        postedWhen: string | null;
+        estimatedLength: {
+            enumValue: string;
+        } | null;
+        isCoaching: boolean | null;
+        isToptalProject: boolean | null;
+    };
+    jobApplication: {
+        id: string;
+        requestedHourlyRate: {
+            decimal: string;
+        } | null;
+    } | null;
+    engagement: {
+        id: string;
+        startDate: string | null;
+        endDate: string | null;
+        commitment: {
+            slug: string;
+        } | null;
+        expectedHours: number | null;
+    } | null;
+}
+/**
+ * Aggregate stats payload returned by `stats()`. `total` is the sum
+ * across all status groups (also the cross-check value — the
+ * unfiltered list call returns the same number); each entry in
+ * `groups` is a server-provided count for the named status group.
+ */
+export interface ApplicationsStats {
+    total: number;
+    groups: {
+        name: StatusGroup;
+        count: number;
+    }[];
+}
+/**
+ * List the signed-in user's job activity items (applications,
+ * availability requests, interviews, engagements).
+ *
+ * Default scope is whatever the server returns when neither filter is
+ * supplied (empirically the full unpaginated set, capped at the
+ * server's default limit). The returned array preserves server order;
+ * the CLI / MCP do not re-sort.
+ *
+ * **AC scope adjustment** (per #15 user decision 2026-05-10): the
+ * operation accepts NO date filter and NO pagination args. `--from` /
+ * `--to` and `--page` / `--per-page` flags are deliberately not exposed
+ * by this leaf; the AC items that referenced them are deferred. See
+ * `.tmp/workitem-15.md` § Open Questions (RESOLVED) for the rationale.
+ */
+export declare function list(token: string, opts?: ListOptions): Promise<JobActivityItem[]>;
+export declare function show(token: string, id: string): Promise<JobActivityItemDetail>;
+/**
+ * Aggregate per-status-group counts plus the overall total. Issues N+1
+ * `JobActivityItems` calls — one per `JobActivityItemStatusGroupEnum`
+ * value — in parallel via `Promise.all`. Each call's
+ * `data.viewer.jobActivityList.totalCount` is a server-provided
+ * scalar; the helper does NOT count the returned `entities` array
+ * (which would be the synthesis the AC forbids).
+ *
+ * `total` is the sum of per-group counts. The unfiltered call's
+ * `totalCount` would yield the same number; we don't issue an extra
+ * call to verify because the per-group sum is already authoritative.
+ *
+ * **Failure mode**: `Promise.all` rejects on the first failed call. A
+ * single GraphQL error on one of the 5 groups loses the 4 successful
+ * counts. This is intentional: `applications stats` is an aggregate;
+ * surfacing partial counts (e.g. "118 total" when one group's call
+ * failed) would be misleading because the user reads `total` as
+ * authoritative. The right behavior on partial failure is "show no
+ * stats and surface the error" — the caller (`runApplicationsStats`)
+ * routes the rejection through the structured error envelope so the
+ * user knows exactly what went wrong.
+ */
+export declare function stats(token: string): Promise<ApplicationsStats>;
+//# sourceMappingURL=index.d.ts.map

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

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