@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/services/applications/index.js

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { callGatewayShared } from "../_shared/transport.js";
+export class ApplicationsError extends Error {
+    code;
+    name = "ApplicationsError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * 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 const STATUS_GROUPS = [
+    "ACTIVE_ENGAGEMENT",
+    "ARCHIVED",
+    "CLOSED_ENGAGEMENT",
+    "ON_CLIENT_REVIEW",
+    "ON_RECRUITER_REVIEW",
+];
+// ---------------------------------------------------------------------
+// GraphQL operation strings (full-document queries — no APQ pinning)
+//
+// Mirror `../research/graphql/gateway/operations/mobile/JobActivityItems.graphql`
+// and `JobActivityItem.graphql`, but with selection sets trimmed to the
+// shape this service surfaces. The operation NAMES are kept verbatim so
+// any future server-side allowlisting that gates on operation name
+// continues to recognize them.
+//
+// **Schema gap acknowledged**: the synthesized SDL at
+// `../research/graphql/gateway/schema.graphql` declares
+// `viewer.jobActivityList: JobActivityList!` and
+// `viewer.jobActivityItem: TalentJobActivityItem!` with NO arguments.
+// The captured operation passes `keywords`, `onlyStatusGroupFilter`,
+// `id` — empirically these work (the mobile app sends them daily). The
+// E2E tests are the authority on this contract.
+// ---------------------------------------------------------------------
+const JOB_ACTIVITY_LIST_QUERY = `query JobActivityItems($keywords: [String!], $onlyStatusGroupFilter: [JobActivityItemStatusGroupEnum!]) {
+  viewer {
+    __typename
+    id
+    jobActivityList(keywords: $keywords, statusGroupV2: { only: $onlyStatusGroupFilter }) {
+      __typename
+      entities {
+        __typename
+        id
+        statusV2 { __typename value verbose }
+        statusGroupV2 { __typename value verbose }
+        statusColor
+        lastUpdatedAt
+        job {
+          __typename
+          id
+          title
+          url
+          client { __typename id fullName }
+        }
+        jobApplication { __typename id }
+        engagement { __typename id }
+        availabilityRequest { __typename id }
+        interview { __typename id }
+      }
+      totalCount
+    }
+  }
+}`;
+const JOB_ACTIVITY_ITEM_QUERY = `query JobActivityItem($id: ID!) {
+  viewer {
+    __typename
+    id
+    jobActivityItem(id: $id) {
+      __typename
+      id
+      statusV2 { __typename value verbose }
+      statusGroupV2 { __typename value verbose }
+      statusColor
+      lastUpdatedAt
+      job {
+        __typename
+        id
+        title
+        url
+        descriptionMd
+        expectedHours
+        startDate
+        postedWhen
+        commitment { __typename slug }
+        workType { __typename slug }
+        specialization { __typename title }
+        estimatedLength { __typename enumValue }
+        isCoaching
+        isToptalProject
+        client { __typename id fullName }
+      }
+      jobApplication {
+        __typename
+        id
+        requestedHourlyRate { __typename decimal }
+      }
+      engagement {
+        __typename
+        id
+        startDate
+        endDate
+        commitment { __typename slug }
+        expectedHours
+      }
+      availabilityRequest { __typename id }
+      interview { __typename id }
+    }
+  }
+}`;
+/**
+ * Thin per-service wrapper around {@link callGatewayShared} (issue
+ * #329). Pins the mobile-gateway surface, the {@link ApplicationsError}
+ * domain class, and the `requireViewer` flag — every `applications`
+ * response carries `viewer` and we surface a `NO_VIEWER` whenever
+ * the session is technically valid but no viewer is bound. The
+ * generic constraint mirrors the previous local helper so call sites
+ * stay type-checked.
+ */
+async function callGateway(token, operationName, query, variables, schema) {
+    return callGatewayShared("mobile-gateway", token, operationName, query, variables, ApplicationsError, { schema, requireViewer: true });
+}
+/**
+ * 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 async function list(token, opts = {}) {
+    const variables = {};
+    if (opts.keywords !== undefined && opts.keywords.length > 0) {
+        variables["keywords"] = opts.keywords;
+    }
+    else {
+        variables["keywords"] = null;
+    }
+    if (opts.statusGroups !== undefined && opts.statusGroups.length > 0) {
+        variables["onlyStatusGroupFilter"] = opts.statusGroups;
+    }
+    else {
+        variables["onlyStatusGroupFilter"] = null;
+    }
+    const data = await callGateway(token, "JobActivityItems", JOB_ACTIVITY_LIST_QUERY, variables);
+    // The cast above is the awkward part of dropping codegen here; the
+    // shape narrowing below is the single source of runtime truth.
+    if (data.viewer === null || data.viewer.jobActivityList === null) {
+        return [];
+    }
+    return data.viewer.jobActivityList.entities ?? [];
+}
+/**
+ * Fetch a single activity item by id.
+ *
+ * Throws `ApplicationsError("NOT_FOUND")` for two distinct wire shapes
+ * — both meaning "id doesn't resolve to a viewable item":
+ *
+ * 1. **Top-level GraphQL error `Record not found`** (the empirical
+ *    happy-sad path — verified live on 2026-05-10). The gateway
+ *    short-circuits with a top-level `errors[]` carrying the literal
+ *    message "Record not found" rather than returning `data: null`.
+ *    `callGateway` raises `GRAPHQL_ERROR`; we catch and translate.
+ * 2. **Successful response with `viewer.jobActivityItem === null`** —
+ *    not observed in practice but kept as defensive coverage in case
+ *    the gateway ever switches to the data-shape sentinel.
+ */
+const NOT_FOUND_MESSAGE_PATTERN = /Record not found/i;
+export async function show(token, id) {
+    let data;
+    try {
+        data = await callGateway(token, "JobActivityItem", JOB_ACTIVITY_ITEM_QUERY, { id });
+    }
+    catch (err) {
+        if (err instanceof ApplicationsError &&
+            err.code === "GRAPHQL_ERROR" &&
+            NOT_FOUND_MESSAGE_PATTERN.test(err.message)) {
+            throw new ApplicationsError("NOT_FOUND", `No activity item found with id "${id}" (or you don't have access to it).`, { cause: err });
+        }
+        throw err;
+    }
+    if (data.viewer === null) {
+        // unreachable in practice — `callGateway` already threw — but the
+        // null check keeps the type narrowing clean.
+        throw new ApplicationsError("NO_VIEWER", "Session is valid but no viewer is bound to it.");
+    }
+    if (data.viewer.jobActivityItem === null) {
+        throw new ApplicationsError("NOT_FOUND", `No activity item found with id "${id}" (or you don't have access to it).`);
+    }
+    return data.viewer.jobActivityItem;
+}
+/**
+ * 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 async function stats(token) {
+    const groupResults = await Promise.all(STATUS_GROUPS.map(async (group) => {
+        const data = await callGateway(token, "JobActivityItems", JOB_ACTIVITY_LIST_QUERY, { keywords: null, onlyStatusGroupFilter: [group] });
+        const count = data.viewer?.jobActivityList?.totalCount ?? 0;
+        return { name: group, count };
+    }));
+    const total = groupResults.reduce((sum, g) => sum + g.count, 0);
+    return { total, groups: groupResults };
+}
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,254 @@
+import type { DryRunPreview } from "../../transport.js";
+/**
+ * Availability-domain error codes. Mirrors the `EngagementsError` /
+ * `ApplicationsError` shape per project convention.
+ *
+ * - `NO_VIEWER`: HTTP 200 + `data.viewer === null` (impossible in
+ *   practice — auth-revoked is signalled differently — but kept for
+ *   defensive coverage).
+ * - `NO_VIEWER_ROLE`: viewer is present but `viewerRole === null`
+ *   (e.g., user is signed in but has no role assigned on the platform).
+ * - `GRAPHQL_ERROR`: top-level `errors[]` from the gateway, not an
+ *   auth-revoked extension.
+ * - `MUTATION_ERROR`: the `MutationResult.errors[]` payload (operation
+ *   succeeded at GraphQL level, but the mutation itself reports
+ *   per-field errors — validation failures, etc.).
+ * - `NETWORK_ERROR`, `UNKNOWN`: standard transport failure modes.
+ *
+ * Auth-revoked failures throw `AuthRevokedError` (cross-cutting
+ * `TtctlError` subclass per #77), not a code on this enum.
+ */
+export type AvailabilityErrorCode = "NO_VIEWER" | "NO_VIEWER_ROLE" | "GRAPHQL_ERROR" | "MUTATION_ERROR" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR" | "UNKNOWN";
+export declare class AvailabilityError extends Error {
+    readonly code: AvailabilityErrorCode;
+    readonly name = "AvailabilityError";
+    constructor(code: AvailabilityErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Time zone projection — matches the wire `TimeZone` type. `value` is the
+ * IANA zone identifier (e.g., `"Europe/Berlin"`) and the canonical input
+ * for `workingHours.set({ timeZone })`. `location` and the offsets are
+ * read-only metadata for human-facing rendering.
+ */
+export interface AvailabilityTimeZone {
+    name: string | null;
+    value: string;
+    location: string | null;
+    utcOffset: string | null;
+    stdOffset: string | null;
+}
+/**
+ * Top-level availability snapshot returned by `show()`.
+ *
+ * Times are `"HH:MM:SS"` strings; null when the field is unset on the
+ * server. `allocatedHours` is a non-negative integer in [0, 80] per the
+ * platform's UI-enforced range (`SetAvailability` validator caps at 80),
+ * or null when unset.
+ */
+export interface AvailabilitySnapshot {
+    /** Viewer id (Viewer.id from the gateway). */
+    viewerId: string;
+    /** Profile id (viewer.viewerRole.profile.id) — needed as the `profileId` field on `UpdateWorkingHoursInput`. Null when the viewer has a role but no bound profile (unusual but defensively handled). */
+    profileId: string | null;
+    /** Time zone, IANA identifier in `.value`. */
+    timeZone: AvailabilityTimeZone | null;
+    /** Daily working hours window start, `"HH:MM:SS"`. */
+    workingTimeFrom: string | null;
+    /** Daily working hours window end, `"HH:MM:SS"`. */
+    workingTimeTo: string | null;
+    /** Flexible shift-range start (the "I could shift to these hours if needed" window). */
+    availableShiftRangeFrom: string | null;
+    /** Flexible shift-range end. */
+    availableShiftRangeTo: string | null;
+    /** Allocated hours (viewer-scoped, integer in [0, 80]). */
+    allocatedHours: number | null;
+}
+/**
+ * Input for `workingHours.set()`. All fields optional — the mutation
+ * supports partial updates. The CLI/MCP surfaces require at least one
+ * field to be provided.
+ */
+export interface UpdateWorkingHoursInput {
+    /** IANA time-zone identifier (e.g., `"Europe/Berlin"`). */
+    timeZone?: string;
+    /** Daily working hours window start, `"HH:MM:SS"`. */
+    workingTimeFrom?: string;
+    /** Daily working hours window end, `"HH:MM:SS"`. */
+    workingTimeTo?: string;
+    /** Flexible shift-range start, `"HH:MM:SS"`. */
+    availableShiftRangeFrom?: string;
+    /** Flexible shift-range end, `"HH:MM:SS"`. */
+    availableShiftRangeTo?: string;
+}
+/**
+ * Per-mutation option object for the dry-run short-circuit (issue #164,
+ * mirroring the #52 / #162 / #163 reference pattern). When `dryRun ===
+ * true`, the mutation builds a {@link DryRunPreview} and returns
+ * `{ kind: "preview", preview }` WITHOUT invoking the gateway transport
+ * — including any pre-fetch the apply path would normally issue (per the
+ * AC's "no GraphQL request is sent (mock transport assertion)"
+ * requirement). Default `false` — the apply path runs and a
+ * `{ kind: "applied", result }` outcome is returned.
+ *
+ * Stand-alone interface (not a discriminated-union option) so future
+ * per-mutation options (e.g. hypothetical idempotency-key parameter)
+ * can extend additively. Uniform across the 2 availability mutations.
+ */
+export interface DryRunOptions {
+    /**
+     * When `true`, short-circuit before any transport call and return a
+     * {@link DryRunPreview}-bearing outcome instead of executing the
+     * mutation. Default: `false` — normal apply path.
+     */
+    dryRun?: boolean;
+}
+/**
+ * Apply-path outcome for {@link workingHours.set}. Wraps the
+ * post-mutation working-hours fields in a discriminated union so
+ * callers can branch deterministically between apply
+ * (`kind: "applied"`) and dry-run (`kind: "preview"`,
+ * see {@link AvailabilityDryRunPreviewOutcome}).
+ */
+export interface WorkingHoursAppliedOutcome {
+    kind: "applied";
+    result: {
+        timeZone: AvailabilityTimeZone | null;
+        workingTimeFrom: string | null;
+        workingTimeTo: string | null;
+        availableShiftRangeFrom: string | null;
+        availableShiftRangeTo: string | null;
+        notice: string | null;
+    };
+}
+/**
+ * Dry-run outcome shared by every availability mutation. Carries a
+ * {@link DryRunPreview} (operation name, surface, transport, endpoint,
+ * variables payload, redacted headers) — emitted verbatim by the CLI's
+ * dry-run envelope (`emitDryRunSuccess` in
+ * `packages/cli/src/lib/envelopes.ts`).
+ */
+export interface AvailabilityDryRunPreviewOutcome {
+    kind: "preview";
+    preview: DryRunPreview;
+}
+/**
+ * Discriminated-union return type for {@link workingHours.set}. Pre-1.0
+ * breaking change vs the pre-#164 return type (the raw result object) —
+ * callers must branch on `outcome.kind` to access either
+ * `outcome.result` or `outcome.preview`.
+ */
+export type WorkingHoursSetOutcome = WorkingHoursAppliedOutcome | AvailabilityDryRunPreviewOutcome;
+/**
+ * Apply-path outcome for {@link allocatedHours.set}.
+ */
+export interface AllocatedHoursAppliedOutcome {
+    kind: "applied";
+    result: {
+        allocatedHours: number;
+        hiredHours: number | null;
+        notice: string | null;
+    };
+}
+/**
+ * Discriminated-union return type for {@link allocatedHours.set}.
+ * Pre-1.0 breaking change vs the pre-#164 return type — callers must
+ * branch on `outcome.kind`.
+ */
+export type AllocatedHoursSetOutcome = AllocatedHoursAppliedOutcome | AvailabilityDryRunPreviewOutcome;
+/**
+ * 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 declare function show(token: string): Promise<AvailabilitySnapshot>;
+/**
+ * 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 declare 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.
+     */
+    show(token: string): Promise<{
+        viewerId: string;
+        timeZone: AvailabilityTimeZone | null;
+        workingTimeFrom: string | null;
+        workingTimeTo: string | null;
+        availableShiftRangeFrom: string | null;
+        availableShiftRangeTo: string | null;
+    }>;
+    /**
+     * 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).
+     */
+    set(token: string, input: UpdateWorkingHoursInput, options?: DryRunOptions): Promise<WorkingHoursSetOutcome>;
+};
+/**
+ * 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 declare 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).
+     */
+    show(token: string): Promise<{
+        allocatedHours: number;
+    }>;
+    /**
+     * 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.
+     */
+    set(token: string, hours: number, options?: DryRunOptions): Promise<AllocatedHoursSetOutcome>;
+};
+//# sourceMappingURL=index.d.ts.map

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

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