@ttctl/core 0.0.0 → 0.1.0-rc.1

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

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

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

@@ -0,0 +1,504 @@
+import type { DryRunPreview } from "../../transport.js";
+/**
+ * Engagements-domain error codes. Mirrors the `ApplicationsError` /
+ * `ProfileError` shape per project convention.
+ *
+ * - `NO_VIEWER`: HTTP 200 + `data.viewer === null` (impossible in
+ *   practice — auth-revoked is signalled differently — but kept for
+ *   defensive coverage).
+ * - `NOT_FOUND`: caller's id doesn't resolve to a viewable engagement.
+ *   Distinct wire shapes both fold into this code (top-level
+ *   `Record not found` GraphQL error AND `data.viewer.jobActivityItem
+ *   === null`).
+ * - `NO_ENGAGEMENT`: the activity row exists but has no engagement
+ *   (e.g., the row is an interview that never became an engagement).
+ *   Specific to `breaks.list` / `breaks.add` which require an
+ *   engagement-bearing row.
+ * - `GRAPHQL_ERROR`: top-level `errors[]` from the gateway, not an
+ *   auth-revoked extension and not a `Record not found`.
+ * - `MUTATION_ERROR`: the `MutationResult.errors[]` payload (operation
+ *   succeeded at GraphQL level, but the mutation itself reports
+ *   per-field errors — break date overlaps, validation failures).
+ * - `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 EngagementsErrorCode = "NO_VIEWER" | "NOT_FOUND" | "NO_ENGAGEMENT" | "GRAPHQL_ERROR" | "MUTATION_ERROR" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR" | "UNKNOWN";
+export declare class EngagementsError extends Error {
+    readonly code: EngagementsErrorCode;
+    readonly name = "EngagementsError";
+    constructor(code: EngagementsErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Engagement-bearing status groups in `JobActivityItemStatusGroupEnum`.
+ * Used both by `list` (default filter) and `stats` (per-group counts).
+ *
+ * Note: `ARCHIVED` is intentionally NOT included — that group includes
+ * archived non-engagement items too (archived applications, archived
+ * interviews). Users wanting an archived engagement view should use
+ * `applications list --status-group ARCHIVED` and filter further.
+ */
+export declare const ENGAGEMENT_STATUS_GROUPS: readonly ["ACTIVE_ENGAGEMENT", "CLOSED_ENGAGEMENT"];
+export type EngagementStatusGroup = (typeof ENGAGEMENT_STATUS_GROUPS)[number];
+/**
+ * Public `--status` filter values for `list`. Maps to one or both
+ * {@link ENGAGEMENT_STATUS_GROUPS} entries.
+ */
+export declare const ENGAGEMENT_LIST_STATUSES: readonly ["active", "past", "all"];
+export type EngagementListStatus = (typeof ENGAGEMENT_LIST_STATUSES)[number];
+/**
+ * Status payload — both `statusV2` (specific) and `statusGroupV2`
+ * (coarse, one of {@link ENGAGEMENT_STATUS_GROUPS}) carry the same shape
+ * on the wire.
+ */
+export interface EngagementStatus {
+    value: string;
+    verbose: string;
+}
+/**
+ * Reference to the job an engagement points at.
+ */
+export interface EngagementJobRef {
+    id: string;
+    title: string | null;
+    url: string | null;
+    client: {
+        id: string;
+        fullName: string | null;
+    } | null;
+}
+/**
+ * One row in the engagements list — surfaced by `engagements list`. The
+ * `id` is the `jobActivityItem.id` (the public engagement id from a
+ * user perspective). `engagementId` is the underlying
+ * `TalentEngagement.id`, exposed so consumers can call mutation paths
+ * directly when they prefer to bypass the internal lookup in
+ * {@link breaks.add}.
+ */
+export interface EngagementListItem {
+    id: string;
+    engagementId: string | null;
+    statusV2: EngagementStatus;
+    statusGroupV2: EngagementStatus;
+    statusColor: string | null;
+    lastUpdatedAt: string;
+    job: EngagementJobRef;
+    startDate: string | null;
+    endDate: string | null;
+    expectedHours: number | null;
+    commitment: {
+        slug: string;
+    } | null;
+}
+/**
+ * One entry in the engagement-break reasons catalog — the server-side
+ * dictionary of valid `--reason-id` values for {@link breaks.add}.
+ *
+ * Source: `platformConfiguration.engagementBreakReasons` (returns
+ * `[FeedbackReason]!` on the wire). Each `FeedbackReason` carries:
+ *   - `identifier` — the value to pass to `breaks.add` as
+ *     `reasonIdentifier` (e.g., `talent_on_vacation`, `other`).
+ *   - `nameForRole` — the human-readable label tailored to the
+ *     talent's role.
+ *
+ * The schema's `FeedbackReason` has no `description` field; AC1's "if
+ * available" allowance lets the surface omit it without breaking the
+ * contract.
+ */
+export interface EngagementBreakReason {
+    identifier: string;
+    nameForRole: string;
+}
+/**
+ * Engagement break wire shape (matches the captured
+ * `engagementBreakData` fragment). `operations` mirrors the schema's
+ * `EngagementBreakOperations` projection — `callable` is a free-text
+ * indicator the server returns to signal whether the operation is
+ * available for this break (active vs cancelled vs already-removed).
+ */
+export interface EngagementBreak {
+    id: string;
+    startDate: string;
+    endDate: string;
+    comment: string | null;
+    operations: {
+        removeEngagementBreak: {
+            callable: string;
+        } | null;
+        rescheduleEngagementBreak: {
+            callable: string;
+        } | null;
+    } | null;
+}
+/**
+ * Detail-view shape for `engagements show <id>`. Extends
+ * {@link EngagementListItem} with additional engagement metadata
+ * (current agreement, bill cycle, earning summary) AND inlines the
+ * current breaks list (so a single `show` call covers what would
+ * otherwise need a follow-up `breaks list`).
+ *
+ * Field selection is conservative — fields the CLI/MCP renders.
+ * `currentAgreement` carries the rate fields the user typically wants
+ * to inspect (their hourly rate, the marketplace margin, the
+ * commitment level). `billCycle.verbose` is the human-readable bill
+ * cycle (`"Monthly"`, `"Bi-weekly"`, etc.). `earning.paid` is
+ * cumulative paid earnings on this engagement.
+ */
+export interface EngagementDetail extends EngagementListItem {
+    currentAgreement: {
+        applicationRate: string | null;
+        talentHourlyRate: string | null;
+        talentRate: string | null;
+        marketplaceMargin: string | null;
+        timePeriod: string | null;
+        commitment: {
+            slug: string;
+        } | null;
+    } | null;
+    billCycle: {
+        verbose: string;
+    } | null;
+    earning: {
+        paid: {
+            decimal: string;
+        } | null;
+    } | null;
+    eligibleForPayment: boolean | null;
+    eligibleToViewTimesheets: boolean | null;
+    eligibleToViewTimeOffs: boolean | null;
+    proposedEnd: {
+        endDate: string | null;
+        status: string | null;
+    } | null;
+    job: EngagementJobRef & {
+        descriptionMd: string | null;
+        expectedHours: number | null;
+        commitment: {
+            slug: string;
+        } | null;
+        workType: {
+            slug: string;
+        } | null;
+        specialization: {
+            title: string;
+        } | null;
+        startDate: string | null;
+        isCoaching: boolean | null;
+        isToptalProject: boolean | null;
+    };
+    breaks: EngagementBreak[];
+}
+/**
+ * Aggregate stats payload returned by `stats()`. `total` is the sum
+ * across {@link ENGAGEMENT_STATUS_GROUPS}; each entry in `groups` is a
+ * server-provided count (`totalCount`).
+ */
+export interface EngagementsStats {
+    total: number;
+    groups: {
+        name: EngagementStatusGroup;
+        count: number;
+    }[];
+}
+/**
+ * Optional list filter.
+ */
+export interface ListOptions {
+    /**
+     * Filter to one of {@link ENGAGEMENT_LIST_STATUSES}. Defaults to
+     * `"active"` per the #147 spec.
+     */
+    status?: EngagementListStatus;
+    /**
+     * Free-text keyword filter (passes through to the gateway's
+     * `keywords` arg, same as `applications list`). Each entry ANDs with
+     * the others.
+     */
+    keywords?: string[];
+}
+/**
+ * Input for `breaks.add`. `reasonIdentifier` is the server-side break
+ * reason key. The mutation requires a non-empty value at the server
+ * (validation rejects empty strings with `code=blank, key=reasonId`);
+ * the caller must supply a valid identifier discovered from the
+ * `platformConfiguration.engagementBreakReasons` catalog. Known
+ * canonical identifiers at time of writing: `talent_on_vacation`,
+ * `client_needs_preparation`, `client_on_vacation`, `other`. Use
+ * {@link breaks.reasonsList} (CLI: `ttctl engagements breaks reasons
+ * list`; MCP: `ttctl_engagements_breaks_reasons_list`) to discover
+ * the live catalog.
+ */
+export interface AddBreakOptions {
+    startDate: string;
+    endDate: string;
+    reasonIdentifier: string;
+    comment?: string;
+}
+/**
+ * Per-mutation option object for the dry-run short-circuit (issue #163,
+ * mirroring the #52 reference pattern on `profile.basic.set()` and the
+ * #162 replication across `jobs`). When `dryRun === true`, the mutation
+ * builds a {@link DryRunPreview} and returns `{ kind: "preview", preview }`
+ * WITHOUT invoking the gateway transport. Default `false` — the apply
+ * path runs and a `{ kind: "applied", result }` outcome is returned.
+ *
+ * Kept as a stand-alone interface (not a discriminated-union option) so
+ * future per-mutation options can extend the same shape additively. The
+ * signature is deliberately uniform across the 2 engagement-breaks
+ * 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.
+     *
+     * **`breaks.add` specifics**: the apply path issues an
+     * `EngagementBreaks` query first to translate `jobActivityItem.id`
+     * → `engagement.id` for the mutation root. The dry-run path SKIPS
+     * that prefetch (per the AC's "no GraphQL request is sent (mock
+     * transport assertion)") and uses the caller-supplied
+     * `jobActivityItemId` as the placeholder value for `engagementId`
+     * in the preview's variables payload. The preview's wire SHAPE
+     * (field names, operation name, surface, redacted headers) is
+     * verbatim; the `engagementId` VALUE is a placeholder that resolves
+     * at apply time. The dry-run envelope carries a `notice` field
+     * surfacing this caveat to the user.
+     */
+    dryRun?: boolean;
+}
+/**
+ * Apply-path outcome for {@link breaks.add}. Wraps the
+ * server-confirmed {@link EngagementBreak} in a discriminated union so
+ * callers can branch deterministically between the apply path
+ * (`kind: "applied"`) and the dry-run path (`kind: "preview"`, see
+ * {@link EngagementBreaksDryRunPreviewOutcome}).
+ */
+export interface EngagementBreakAddAppliedOutcome {
+    kind: "applied";
+    result: EngagementBreak;
+}
+/**
+ * Apply-path outcome for {@link breaks.remove}. Carries the
+ * `{ id }` confirmation that the wire's `CancelEngagementBreak`
+ * mutation returns.
+ */
+export interface EngagementBreakRemoveAppliedOutcome {
+    kind: "applied";
+    result: {
+        id: string;
+    };
+}
+/**
+ * Input for {@link breaks.reschedule} (#155). The wire mutation
+ * (`RescheduleEngagementBreak`) accepts only `startDate` + `endDate` in
+ * its input block — there is NO `comment` field, NO `reasonIdentifier`
+ * field. The server preserves the existing break's reason and comment
+ * across the reschedule; callers wanting to also change those fields
+ * must `remove` + `add` instead.
+ */
+export interface RescheduleBreakOptions {
+    startDate: string;
+    endDate: string;
+}
+/**
+ * Apply-path outcome for {@link breaks.reschedule}. Wraps the
+ * server-confirmed {@link EngagementBreak} (with refreshed dates) in a
+ * discriminated union so callers branch deterministically on apply vs
+ * dry-run. The "result" is the FULL break record (post-reschedule), not
+ * just the diff — matches the apply-path semantics of
+ * {@link breaks.add}, NOT {@link breaks.remove}.
+ */
+export interface EngagementBreakRescheduleAppliedOutcome {
+    kind: "applied";
+    result: EngagementBreak;
+}
+/**
+ * Dry-run outcome shared by every engagement-breaks 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 EngagementBreaksDryRunPreviewOutcome {
+    kind: "preview";
+    preview: DryRunPreview;
+}
+/**
+ * Discriminated-union return type for {@link breaks.add}. The apply
+ * path returns the post-mutation {@link EngagementBreak} wrapped in
+ * `{ kind: "applied", result }`; the dry-run path returns a
+ * {@link DryRunPreview} wrapped in `{ kind: "preview", preview }`.
+ *
+ * Pre-1.0 the pre-#163 return type (`Promise<EngagementBreak>`) no
+ * longer exists — callers must branch on `outcome.kind` to access
+ * either `outcome.result` or `outcome.preview`. The MCP layer (and any
+ * future consumer) updates in lockstep with this rename via the
+ * `unwrapEngagementOutcome` generic in
+ * `packages/mcp/src/tools/engagements.ts`.
+ */
+export type AddBreakOutcome = EngagementBreakAddAppliedOutcome | EngagementBreaksDryRunPreviewOutcome;
+/**
+ * Discriminated-union return type for {@link breaks.remove}.
+ */
+export type RemoveBreakOutcome = EngagementBreakRemoveAppliedOutcome | EngagementBreaksDryRunPreviewOutcome;
+/**
+ * Discriminated-union return type for {@link breaks.reschedule}. The
+ * apply path returns the post-mutation {@link EngagementBreak} wrapped
+ * in `{ kind: "applied", result }`; the dry-run path returns a
+ * {@link DryRunPreview} wrapped in `{ kind: "preview", preview }`.
+ */
+export type RescheduleBreakOutcome = EngagementBreakRescheduleAppliedOutcome | EngagementBreaksDryRunPreviewOutcome;
+/**
+ * List the signed-in user's engagements.
+ *
+ * Default scope is active engagements only (`status: "active"` →
+ * `ACTIVE_ENGAGEMENT`). `status: "past"` returns closed engagements
+ * (`CLOSED_ENGAGEMENT`); `status: "all"` returns both.
+ *
+ * The returned array preserves server order; the CLI / MCP do not
+ * re-sort.
+ */
+export declare function list(token: string, opts?: ListOptions): Promise<EngagementListItem[]>;
+/**
+ * Fetch a single engagement's detail by `jobActivityItem.id`.
+ *
+ * Throws `EngagementsError("NOT_FOUND")` when the id doesn't resolve
+ * (matches `applications.show` semantics — both the
+ * "Record not found" GraphQL error path AND the data-shape sentinel
+ * `viewer.jobActivityItem === null`).
+ *
+ * Throws `EngagementsError("NO_ENGAGEMENT")` when the row exists but
+ * has no engagement (e.g., an interview-only row that never reached
+ * engagement status).
+ */
+export declare function show(token: string, id: string): Promise<EngagementDetail>;
+/**
+ * Aggregate per-engagement-status-group counts plus the overall total.
+ * Issues 2 calls in parallel (one per {@link ENGAGEMENT_STATUS_GROUPS}
+ * value).
+ *
+ * Each `count` is server-provided (`totalCount`), no client-side
+ * synthesis.
+ */
+export declare function stats(token: string): Promise<EngagementsStats>;
+/**
+ * Engagement breaks management. Sub-namespace under the service so the
+ * public surface stays `engagements.breaks.{list, add, remove, reschedule}` —
+ * matches the CLI verb path `engagements breaks {list, add, remove, reschedule}`.
+ */
+export declare const breaks: {
+    /**
+     * List breaks for an engagement (by `jobActivityItem.id`).
+     *
+     * Reuses the captured `EngagementBreaks` operation verbatim. The
+     * returned array preserves server order.
+     */
+    list(token: string, jobActivityItemId: string): Promise<EngagementBreak[]>;
+    /**
+     * Schedule a new break on an engagement (by `jobActivityItem.id`).
+     *
+     * Internally fetches the underlying `engagement.id` first
+     * ({@link fetchEngagementBreaksAndId}) — adds one round-trip but
+     * keeps the CLI/MCP surface consistent (the user always passes the
+     * activity-item id, never the underlying engagement id).
+     *
+     * `reasonIdentifier` is the server-side reason key. The mutation
+     * marks it `String!` AND the server rejects empty strings (validated
+     * by live API: `code=blank, key=reasonId`), so the caller must
+     * supply a valid value — see {@link AddBreakOptions} for the known
+     * catalog and the discovery path.
+     *
+     * Throws `EngagementsError("MUTATION_ERROR")` when the gateway
+     * returns `success: false` (overlapping break dates, validation
+     * failures, etc.).
+     *
+     * Dry-run path (issue #163): when invoked with `options.dryRun ===
+     * true`, builds a {@link DryRunPreview} of the mutation WITHOUT
+     * invoking the gateway transport — including the prefetch
+     * `EngagementBreaks` query (per the AC's "no GraphQL request is
+     * sent" requirement). The preview's `variables.engagementId` is
+     * populated with the caller-supplied `jobActivityItemId` as a
+     * placeholder; the wire SHAPE (field names, operation, surface,
+     * redacted headers) is verbatim. The actual `engagement.id` resolves
+     * at apply time via the skipped prefetch.
+     */
+    add(token: string, jobActivityItemId: string, opts: AddBreakOptions, options?: DryRunOptions): Promise<AddBreakOutcome>;
+    /**
+     * Fetch the engagement-break reasons catalog — the valid
+     * `--reason-id` values for {@link breaks.add}.
+     *
+     * Issues `PlatformConfiguration` against the mobile gateway with a
+     * minimal projection (`engagementBreakReasons { identifier
+     * nameForRole }`). Returns a defensively-cleaned, sorted-by-identifier
+     * list:
+     *   - null wire entries (`[FeedbackReason]!` — list non-null but
+     *     items nullable per Toptal SDL convention) are filtered out.
+     *   - sort is locale-independent, case-insensitive on `identifier`
+     *     so consumers get a stable, predictable order across runs.
+     *
+     * **CLAUDE.md schema/contract**: this operation is hand-authored
+     * (NOT in `codegen.config.ts`) → live E2E coverage required pre-merge.
+     * See `packages/e2e/src/29-engagements-breaks-reasons.e2e.test.ts`.
+     *
+     * `EngagementsError("NO_VIEWER")` is not raised here:
+     * `platformConfiguration` is a viewer-agnostic root field on the
+     * gateway (the catalog is the same regardless of viewer), so the
+     * `data.viewer === null` defensive branch from the other operations
+     * does not apply. Auth failures still surface via `AuthRevokedError`
+     * per the standard `callGateway` semantics.
+     */
+    reasonsList(token: string): Promise<EngagementBreakReason[]>;
+    /**
+     * Cancel a break by `engagementBreak.id`. The id is what
+     * `breaks.list` returns; users can copy it directly.
+     *
+     * Returns `{ id }` of the cancelled break for envelope wrapping.
+     * Throws `EngagementsError("MUTATION_ERROR")` on `success: false`.
+     *
+     * Dry-run path (issue #163): when invoked with `options.dryRun ===
+     * true`, builds a {@link DryRunPreview} of the mutation without
+     * invoking the gateway transport and returns it wrapped in
+     * {@link EngagementBreaksDryRunPreviewOutcome}. The single
+     * `engagementBreakId` variable is preserved verbatim — no
+     * translation needed for this mutation.
+     */
+    remove(token: string, engagementBreakId: string, options?: DryRunOptions): Promise<RemoveBreakOutcome>;
+    /**
+     * Reschedule an existing break to a new date window by
+     * `engagementBreak.id` (#155). The id is what `breaks.list` returns
+     * (and what `breaks.add` returns after creating one); users can pass
+     * it directly without any translation. The mutation root is
+     * `engagementBreak(id: $engagementBreakId)` — same root as
+     * {@link breaks.remove}, NOT
+     * `engagement(id: ...).rescheduleBreak(...)` — so no engagement-id
+     * prefetch is needed (unlike {@link breaks.add}).
+     *
+     * The wire input has only `startDate` + `endDate`. There is NO
+     * `comment` or `reasonIdentifier` field on the mutation input — the
+     * server preserves the existing break's reason and comment across the
+     * reschedule. Callers wanting to change those fields must
+     * `remove` + `add` instead.
+     *
+     * Returns the FULL post-mutation {@link EngagementBreak} (with
+     * refreshed dates + preserved comment/operations), wrapped in the
+     * apply outcome — mirroring {@link breaks.add}, not
+     * {@link breaks.remove} (which returns only `{ id }` because cancel
+     * has nothing meaningful to surface).
+     *
+     * Throws `EngagementsError("NOT_FOUND")` when the break id resolves
+     * to `null engagementBreak`; throws `EngagementsError("MUTATION_ERROR")`
+     * when the gateway returns `success: false` (overlapping windows,
+     * validation failures).
+     *
+     * Dry-run path: when invoked with `options.dryRun === true`, builds a
+     * {@link DryRunPreview} of the mutation without invoking the gateway
+     * transport. The single trio `{ engagementBreakId, startDate, endDate }`
+     * is preserved verbatim — no translation needed.
+     */
+    reschedule(token: string, engagementBreakId: string, opts: RescheduleBreakOptions, options?: DryRunOptions): Promise<RescheduleBreakOutcome>;
+};
+//# sourceMappingURL=index.d.ts.map

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

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