@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/services/profile/visas/index.js

@@ -0,0 +1,306 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { AuthRevokedError, TtctlError } from "../../../auth/errors.js";
+import { impersonatedTransport } from "../../../transport.js";
+import { extractProfileId, isAuthRevokedExtensionCode } from "../shared.js";
+export class VisasError extends Error {
+    code;
+    name = "VisasError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** Map a server `TravelVisa` node to the typed {@link TravelVisa}. */
+function mapTravelVisaNode(node) {
+    const country = (node["country"] ?? {});
+    const id = node["id"];
+    return {
+        id: typeof id === "string" ? id : "",
+        countryId: country.id ?? "",
+        countryName: country.name ?? "",
+        visaType: node["visaType"] ?? "",
+        expiryDate: node["expiryDate"] ?? null,
+    };
+}
+/**
+ * Common "200 with errors" shape handler. Returns the unwrapped payload
+ * (the value of the single root data field) as `unknown`; callers
+ * narrow to their per-operation payload shape at the call site.
+ */
+function unwrapResponse(res, operationName) {
+    if (res.status === 401) {
+        throw new AuthRevokedError("Session is invalid or expired.");
+    }
+    if (res.status < 200 || res.status >= 300) {
+        throw new VisasError("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 VisasError("GRAPHQL_ERROR", `${operationName} failed: ${first?.message ?? "GraphQL error"}`);
+    }
+    if (!body?.data) {
+        throw new VisasError("UNKNOWN", `${operationName} response had no \`data\` field`);
+    }
+    const keys = Object.keys(body.data);
+    if (keys.length === 0) {
+        throw new VisasError("UNKNOWN", `${operationName} response had empty \`data\``);
+    }
+    const firstKey = keys[0];
+    const payload = body.data[firstKey];
+    if (payload === null || payload === undefined) {
+        throw new VisasError("UNKNOWN", `${operationName} response had \`null\` payload`);
+    }
+    return payload;
+}
+function rejectIfUserErrors(errors, operationName) {
+    if (Array.isArray(errors) && errors.length > 0) {
+        const first = errors[0];
+        const fieldHint = first?.key ? ` (${first.key})` : "";
+        throw new VisasError("USER_ERROR", `${operationName} rejected${fieldHint}: ${first?.message ?? "unknown error"}`);
+    }
+}
+async function withTransportErrors(operationName, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof TtctlError)
+            throw err;
+        if (err instanceof VisasError)
+            throw err;
+        throw new VisasError("NETWORK_ERROR", `${operationName} request failed: ${err.message}`, {
+            cause: err,
+        });
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*                                Operations                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Full-document `getTravelVisas` query (talent-profile).
+ *
+ * The `Profile.travelVisas` field is only defined on the `talent-profile`
+ * schema — `mobile-gateway` does not expose it (verified against
+ * `research/graphql/talent_profile/operations/getTravelVisas.graphql` and
+ * the synthesized SDLs under `research/graphql/`). Sibling mutations
+ * (`createTravelVisa`, `updateTravelVisa`, `removeTravelVisa`) already
+ * route through `talent-profile` for the same reason; this read aligns
+ * with that surface choice.
+ */
+const GET_TRAVEL_VISAS_QUERY = `query getTravelVisas($profileId: ID!) {
+  profile(id: $profileId) {
+    id
+    travelVisas {
+      nodes {
+        id
+        country {
+          id
+          name
+        }
+        visaType
+        expiryDate
+      }
+    }
+  }
+}`;
+/**
+ * Fetch the signed-in user's travel-visa records. Empty list returns `[]`,
+ * never `null`.
+ */
+export async function list(token) {
+    const profileId = await extractProfileId(token);
+    const res = await withTransportErrors("getTravelVisas", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "getTravelVisas",
+            query: GET_TRAVEL_VISAS_QUERY,
+            variables: { profileId },
+        },
+    }));
+    const profile = unwrapResponse(res, "getTravelVisas");
+    return profile.travelVisas.nodes.map(mapTravelVisaNode);
+}
+const CREATE_TRAVEL_VISA_MUTATION = `mutation createTravelVisa($input: CreateTravelVisaInput!) {
+  createTravelVisa(input: $input) {
+    profile {
+      id
+      travelVisas {
+        nodes {
+          id
+          country {
+            id
+            name
+          }
+          visaType
+          expiryDate
+        }
+      }
+    }
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Create a new travel-visa record.
+ *
+ * Both `countryId` and `visaType` are required by the AC; `expiryDate`
+ * is optional. The wire-side error path returns `errors[]` on the
+ * mutation payload when the server rejects (e.g. unknown country,
+ * malformed date) — those collapse into `USER_ERROR`.
+ */
+export async function add(token, input) {
+    if (!input.countryId || input.countryId.trim() === "") {
+        throw new VisasError("VALIDATION_ERROR", "Travel visa requires a non-empty `countryId`.");
+    }
+    if (!input.visaType || input.visaType.trim() === "") {
+        throw new VisasError("VALIDATION_ERROR", "Travel visa requires a non-empty `visaType`.");
+    }
+    const profileId = await extractProfileId(token);
+    const variables = {
+        input: { profileId, travelVisa: input },
+    };
+    const res = await withTransportErrors("createTravelVisa", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "createTravelVisa",
+            query: CREATE_TRAVEL_VISA_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "createTravelVisa");
+    rejectIfUserErrors(payload.errors, "createTravelVisa");
+    if (!payload.profile) {
+        throw new VisasError("UNKNOWN", "createTravelVisa succeeded but response had no profile payload.");
+    }
+    return payload.profile.travelVisas.nodes.map(mapTravelVisaNode);
+}
+const UPDATE_TRAVEL_VISA_MUTATION = `mutation updateTravelVisa($input: UpdateTravelVisaInput!) {
+  updateTravelVisa(input: $input) {
+    profile {
+      id
+      travelVisas {
+        nodes {
+          id
+          country {
+            id
+            name
+          }
+          visaType
+          expiryDate
+        }
+      }
+    }
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Update a travel-visa record by id.
+ *
+ * `UpdateTravelVisaInput.travelVisa` is treated as a **full-document
+ * replacement** by the server — `countryId` and `visaType` are
+ * non-nullable on the input even when the caller doesn't want to change
+ * them. Sending only the patched field returns
+ * `Variable $input of type UpdateTravelVisaInput! was provided invalid
+ * value for travelVisa.countryId/visaType (Expected value to not be
+ * null)` (verified live 2026-05-15, see #317).
+ *
+ * To preserve the partial-update UX over the full-replace wire shape,
+ * this function does read-modify-write: fetch the current record via
+ * {@link list}, merge caller's `changes` on top of the current state,
+ * then send the merged input. Same pattern as
+ * `services/profile/portfolio/index.ts` `update` (PR #323 / #314).
+ */
+export async function update(token, id, changes) {
+    if (Object.keys(changes).length === 0) {
+        throw new VisasError("VALIDATION_ERROR", "Travel visa update requires at least one field.");
+    }
+    // Read-modify-write: see function doc-comment.
+    const current = (await list(token)).find((v) => v.id === id);
+    if (!current) {
+        throw new VisasError("VALIDATION_ERROR", `Travel visa ${id} not found.`);
+    }
+    // `expiryDate` is `string | null` on the read side but `string | undefined`
+    // on the write side; the conditional spread satisfies
+    // `exactOptionalPropertyTypes: true` (omit when null, value when string).
+    const merged = {
+        countryId: current.countryId,
+        visaType: current.visaType,
+        ...(current.expiryDate !== null && { expiryDate: current.expiryDate }),
+        ...changes,
+    };
+    const variables = {
+        input: { travelVisaId: id, travelVisa: merged },
+    };
+    const res = await withTransportErrors("updateTravelVisa", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "updateTravelVisa",
+            query: UPDATE_TRAVEL_VISA_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "updateTravelVisa");
+    rejectIfUserErrors(payload.errors, "updateTravelVisa");
+    if (!payload.profile) {
+        throw new VisasError("UNKNOWN", "updateTravelVisa succeeded but response had no profile payload.");
+    }
+    return payload.profile.travelVisas.nodes.map(mapTravelVisaNode);
+}
+const REMOVE_TRAVEL_VISA_MUTATION = `mutation removeTravelVisa($input: RemoveTravelVisaInput!) {
+  removeTravelVisa(input: $input) {
+    profile {
+      id
+      travelVisas {
+        nodes {
+          id
+          country {
+            id
+            name
+          }
+          visaType
+          expiryDate
+        }
+      }
+    }
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/** Remove a travel-visa record by id. */
+export async function remove(token, id) {
+    const variables = { input: { travelVisaId: id } };
+    const res = await withTransportErrors("removeTravelVisa", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "removeTravelVisa",
+            query: REMOVE_TRAVEL_VISA_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "removeTravelVisa");
+    rejectIfUserErrors(payload.errors, "removeTravelVisa");
+    if (!payload.profile) {
+        throw new VisasError("UNKNOWN", "removeTravelVisa succeeded but response had no profile payload.");
+    }
+    return payload.profile.travelVisas.nodes.map(mapTravelVisaNode);
+}
+//# sourceMappingURL=index.js.map

package/dist/services/profile/visas/index.js.map

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

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

@@ -0,0 +1,326 @@
+import type { DryRunPreview } from "../../transport.js";
+/**
+ * Timesheet-domain error codes. Mirrors the `EngagementsError` /
+ * `ApplicationsError` shape per project convention.
+ *
+ * - `NO_VIEWER`: HTTP 200 + `data.viewer === null` (defensive — should
+ *   never happen with a valid token).
+ * - `NOT_FOUND`: the supplied id (billing cycle or engagement) does
+ *   not resolve. The wire shape can surface this either as a top-level
+ *   `Record not found` GraphQL error OR as `data.node === null` /
+ *   `data.viewer.jobActivityItem === null`.
+ * - `NO_ENGAGEMENT`: the activity row exists but has no engagement
+ *   (e.g., an interview-only row that never became an engagement). The
+ *   timesheet domain can't operate on such rows.
+ * - `NO_CURRENT_CYCLE`: {@link resolveCurrentCycle} returned zero
+ *   matches — used by the CLI's submit auto-resolve path so callers
+ *   can distinguish "nothing to submit" from "id was invalid".
+ * - `MULTIPLE_CURRENT_CYCLES`: {@link resolveCurrentCycle} returned
+ *   more than one match — used by the CLI's submit auto-resolve path
+ *   so callers can prompt the user to disambiguate. The error carries
+ *   the candidate list on `EngagementsError.cause` (not exposed via
+ *   typing; callers use `resolveCurrentCycle` directly when they need
+ *   structured access).
+ * - `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 from
+ *   `SubmitTimesheet` (the wire operation succeeded at GraphQL level,
+ *   but the submission itself reports per-field errors — overdue,
+ *   missing required hours, 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 TimesheetErrorCode = "NO_VIEWER" | "NOT_FOUND" | "NO_ENGAGEMENT" | "NO_CURRENT_CYCLE" | "MULTIPLE_CURRENT_CYCLES" | "GRAPHQL_ERROR" | "MUTATION_ERROR" | "NETWORK_ERROR" | "WIRE_SHAPE_ERROR" | "UNKNOWN";
+export declare class TimesheetError extends Error {
+    readonly code: TimesheetErrorCode;
+    readonly name = "TimesheetError";
+    constructor(code: TimesheetErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Minimum-commitment payload mirrored from the captured
+ * `minimumCommitmentData` fragment. When `applicable === false`, the
+ * server explains via `reasonNotApplicable`.
+ */
+export interface TimesheetMinimumCommitment {
+    applicable: boolean;
+    minimumHours: number | null;
+    reasonNotApplicable: string | null;
+}
+/**
+ * Reference to the engagement+job a billing cycle belongs to. The id
+ * carried here is the underlying `TalentEngagement.id`, NOT the
+ * `JobActivityItem.id` exposed by `engagements list`. Callers that
+ * need to cross-reference back to the engagements row should use
+ * `engagements list` and match on `engagementId`.
+ */
+export interface TimesheetEngagementRef {
+    id: string;
+    job: {
+        id: string;
+        title: string | null;
+        client: {
+            id: string;
+            fullName: string | null;
+        } | null;
+    };
+}
+/**
+ * One row in the timesheet list — surfaced by `timesheet list`. Wire
+ * type for `hours` is a string (e.g., `"8.0"`) — preserved as-is so
+ * the CLI can render it verbatim without decimal-precision surprises.
+ *
+ * `timesheetSubmissionOpenDatetime` / `timesheetSubmissionDeadlineDatetime`
+ * carry the wire ISO-8601 datetime strings. The CLI may render only
+ * the date portion in pretty output.
+ */
+export interface TimesheetListItem {
+    /** BillingCycle.id — the public timesheet id. */
+    id: string;
+    startDate: string;
+    endDate: string;
+    hours: string;
+    minimumCommitment: TimesheetMinimumCommitment | null;
+    timesheetOverdue: boolean;
+    timesheetSubmissionOpenDatetime: string | null;
+    timesheetSubmissionDeadlineDatetime: string | null;
+    timesheetSubmitted: boolean;
+    engagement: TimesheetEngagementRef;
+}
+/**
+ * One time-entry within a timesheet (per-day duration). `duration` is
+ * the canonical wire field — a **string-encoded decimal** in **minutes**
+ * (e.g., `"480.0"` for an 8-hour day, `"0.0"` for a zero-hour day).
+ * `note` may be empty/null; `isDayOff === true` rows represent a marked
+ * day off and typically carry `duration === "0.0"`.
+ *
+ * **Wire-shape history**: this field was declared as `duration: number`
+ * (presumed seconds) until 2026-05-14. The live mobile-gateway returns
+ * a string-encoded minutes value, empirically captured during the first
+ * end-to-end `SubmitTimesheet` mutation run. The previous declaration
+ * caused `ttctl timesheet show` to render an 8-hour day as `0.13h`
+ * (because `"480.0" / 3600 ≈ 0.133`). See
+ * `.tmp/timesheet-submit-e2e-20260514/{01-before-show,03-submit}.json`
+ * for the originating capture.
+ */
+export interface TimesheetRecord {
+    date: string;
+    duration: string;
+    note: string | null;
+    isDayOff: boolean;
+}
+/**
+ * Detail-view shape for `timesheet show <id>`. Extends
+ * {@link TimesheetListItem} with the timesheet records, the comment,
+ * the rate-card snapshot, and the points-of-contact projection from
+ * the engagement.
+ *
+ * Field selection mirrors the captured `timesheetDetailsFields`
+ * fragment.
+ */
+export interface TimesheetDetail extends TimesheetListItem {
+    timesheetUrl: string | null;
+    timesheetComment: string | null;
+    timesheetRecords: TimesheetRecord[];
+    actualAgreement: {
+        applicationRate: string | null;
+        talentHourlyRate: string | null;
+        marketplaceMargin: string | null;
+    } | null;
+    engagement: TimesheetEngagementRef & {
+        expectedHours: number | null;
+    };
+}
+/**
+ * Optional list filter.
+ */
+export interface ListOptions {
+    /**
+     * When set, scope the listing to the given engagement (the
+     * `JobActivityItem.id` from `engagements list`, NOT the underlying
+     * `TalentEngagement.id`). Switches the wire query from
+     * `PendingTimesheets` (viewer-wide pending-only) to
+     * `Timesheets(jobActivityItemId)` (all cycles for that engagement,
+     * regardless of submission state).
+     */
+    engagement?: string;
+}
+/**
+ * Result of {@link resolveCurrentCycle}.
+ *
+ * - `kind: "found"` — exactly one cycle's submission window contains
+ *   "today" AND it's not yet submitted. Submit by `cycle.id`.
+ * - `kind: "none"` — zero cycles match. Either the user is too early
+ *   (before the next cycle's `submissionOpenDatetime`) or too late
+ *   (after the deadline of every pending cycle).
+ * - `kind: "multiple"` — more than one cycle matches. The CLI prompts
+ *   the user to disambiguate by explicit id.
+ */
+export type CurrentCycleResolution = {
+    kind: "found";
+    cycle: TimesheetListItem;
+} | {
+    kind: "none";
+} | {
+    kind: "multiple";
+    candidates: TimesheetListItem[];
+};
+/**
+ * Per-mutation option object for the dry-run short-circuit. Mirrors
+ * `engagements.DryRunOptions` (issue #163) and the CLI-global
+ * `--dry-run` flag (#52). When `dryRun === true`, {@link submit}
+ * 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.
+ *
+ * **`submit` specifics**: the apply path takes `id: string`
+ * (BillingCycle.id) and submits unconditionally. The dry-run path
+ * builds the preview directly off the supplied id. When the CLI
+ * runner is in auto-resolve mode (no positional id, dry-run engaged),
+ * it stamps a literal placeholder string (e.g.
+ * `<auto-resolved-at-apply-time>`) into `id` so the preview's
+ * `variables.id` is well-named and clearly NOT a real cycle id; the
+ * apply path resolves the real id via
+ * {@link resolveCurrentCycle} before submitting.
+ */
+export interface DryRunOptions {
+    dryRun?: boolean;
+}
+/**
+ * Apply-path outcome for {@link submit}. Wraps the
+ * post-submission {@link TimesheetDetail} in a discriminated union so
+ * callers can branch deterministically between the apply path
+ * (`kind: "applied"`) and the dry-run path
+ * (`kind: "preview"`, see {@link TimesheetDryRunPreviewOutcome}).
+ */
+export interface TimesheetSubmitAppliedOutcome {
+    kind: "applied";
+    result: TimesheetDetail;
+}
+/**
+ * Dry-run outcome for {@link submit}. Carries the
+ * {@link DryRunPreview} (operation name, surface, transport,
+ * endpoint, variables payload, redacted bearer header) — emitted
+ * verbatim by the CLI's dry-run envelope (`emitDryRunSuccess`).
+ */
+export interface TimesheetDryRunPreviewOutcome {
+    kind: "preview";
+    preview: DryRunPreview;
+}
+/**
+ * Discriminated-union return type for {@link submit}.
+ */
+export type SubmitOutcome = TimesheetSubmitAppliedOutcome | TimesheetDryRunPreviewOutcome;
+/**
+ * Optional inputs for {@link resolveCurrentCycle}.
+ */
+export interface ResolveCurrentCycleOptions {
+    /**
+     * Same semantic as {@link ListOptions.engagement}: scope the
+     * resolve to one engagement. When set, the helper switches its
+     * underlying query from `PendingTimesheets` to
+     * `Timesheets(jobActivityItemId)` and filters to
+     * `timesheetSubmitted === false` client-side.
+     */
+    engagement?: string;
+    /**
+     * Override "now" for deterministic tests. Defaults to
+     * `new Date()` at call time.
+     */
+    now?: Date;
+}
+/**
+ * List the signed-in user's timesheet billing cycles.
+ *
+ * Default (no `engagement` option): uses `PendingTimesheets` to fetch
+ * viewer-wide cycles that still need submission. This is the
+ * "what needs my attention" view.
+ *
+ * With `engagement` option: uses `Timesheets($jobActivityItemId)` to
+ * fetch ALL cycles for that engagement (regardless of submission
+ * state). The argument is the public `JobActivityItem.id` exposed by
+ * `engagements list`.
+ *
+ * The returned array preserves server order; the CLI / MCP do not
+ * re-sort.
+ */
+export declare function list(token: string, opts?: ListOptions): Promise<TimesheetListItem[]>;
+/**
+ * Fetch a single timesheet's detail by `BillingCycle.id`.
+ *
+ * Uses the gateway's `node(id)` polymorphic root with the captured
+ * `timesheetDetailsFields` fragment. Throws
+ * `TimesheetError("NOT_FOUND")` when the id doesn't resolve (matches
+ * both the `Record not found` GraphQL error path AND the data-shape
+ * sentinel `data.node === null`).
+ *
+ * Throws `TimesheetError("UNKNOWN")` if the node resolves but isn't a
+ * `BillingCycle` — that would be a wire surprise (a different `node`
+ * type carrying our fragment) and warrants surfacing rather than
+ * silent type-coercion.
+ */
+export declare function show(token: string, id: string): Promise<TimesheetDetail>;
+/**
+ * Resolve the "current" pending timesheet — the billing cycle whose
+ * submission window contains `now` AND which is not yet submitted.
+ *
+ * - `kind: "found"`: exactly one cycle matches.
+ * - `kind: "none"`: zero cycles match (too early before next window,
+ *   too late after every cycle's deadline, or no engagements have
+ *   timesheets enabled).
+ * - `kind: "multiple"`: more than one cycle matches (parallel
+ *   engagements with overlapping current windows).
+ *
+ * When `opts.engagement` is provided, the resolution scopes to that
+ * engagement (uses `Timesheets($jobActivityItemId)` + client-side
+ * filter to `timesheetSubmitted === false`). Otherwise uses
+ * `PendingTimesheets` (server-side filtered).
+ *
+ * The `now` option exists for deterministic testing; production code
+ * paths pass nothing and the helper uses `new Date()`.
+ */
+export declare function resolveCurrentCycle(token: string, opts?: ResolveCurrentCycleOptions): Promise<CurrentCycleResolution>;
+/**
+ * Submit a timesheet for billing.
+ *
+ * **Destructive**: the submission is one-way at the wire level — once
+ * submitted, the timesheet enters Toptal's billing pipeline. Callers
+ * (CLI / MCP) are responsible for end-user confirmation.
+ *
+ * `id` is the BillingCycle.id from `list()` / `show()`. Returns the
+ * post-submission detail payload (with `timesheetSubmitted: true`)
+ * wrapped in `{ kind: "applied", result }` on the apply path.
+ *
+ * Dry-run path (`options.dryRun === true`): builds a
+ * {@link DryRunPreview} of the mutation WITHOUT invoking the
+ * gateway transport. Returns `{ kind: "preview", preview }`. The
+ * CLI's `--dry-run` flag flows through here so the destructive
+ * mutation is never sent in preview mode. See {@link DryRunOptions}
+ * for the placeholder-id semantics when the CLI is in auto-resolve
+ * mode.
+ *
+ * Throws (apply path only — dry-run never throws domain errors):
+ * - `TimesheetError("NOT_FOUND")` when the id doesn't resolve to a
+ *   billing cycle the viewer can submit AND the server is willing to
+ *   communicate that as a structured error (Relay-style global-id
+ *   decode failure, matched via {@link NOT_FOUND_MESSAGE_PATTERN}).
+ * - `TimesheetError("GRAPHQL_ERROR")` when the server returns a
+ *   top-level GraphQL error other than the Relay decode pattern.
+ *   Empirically (E2E 2026-05-12), Toptal's `SubmitTimesheet` returns
+ *   `"500: Internal Server Error"` for syntactically valid but
+ *   non-existent BillingCycle ids — the wire does not pre-validate the
+ *   id, so the 500 surfaces verbatim. The CLI presents it as
+ *   `GRAPHQL_ERROR` (not `NOT_FOUND`) to avoid misleading the caller
+ *   into thinking the id was definitively absent vs. the server
+ *   genuinely failed.
+ * - `TimesheetError("MUTATION_ERROR")` when the server reports
+ *   `success: false` on `MutationResult` (commonly: missing required
+ *   hours, already submitted, deadline passed). The message carries
+ *   the server-side error code+key+message tuples.
+ */
+export declare function submit(token: string, id: string, options?: DryRunOptions): Promise<SubmitOutcome>;
+//# sourceMappingURL=index.d.ts.map

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

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