@ttctl/core 0.0.0 → 0.1.0-rc.1

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

@@ -0,0 +1,833 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { AuthRevokedError, TtctlError } from "../../../auth/errors.js";
+import { impersonatedMultipartTransport, impersonatedTransport } from "../../../transport.js";
+import { extractProfileId, isAuthRevokedExtensionCode } from "../shared.js";
+import { list as listSkills } from "../skills/index.js";
+export class PortfolioError extends Error {
+    code;
+    name = "PortfolioError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * Portfolio item kind enumeration. Empirically the server requires this
+ * as a non-null field on `CreatePortfolioItemInput.portfolioItem`. The
+ * WRITE-side enum uses **lowercase snake_case** values — the
+ * SCREAMING_SNAKE forms returned by the read-side `PortfolioItemKindEnum`
+ * in `research/graphql/gateway/schema.graphql` are REJECTED on create
+ * with `"kind: is not included in the list"` (verified live 2026-05-16
+ * during issue #314 investigation, see `.tmp/probe-portfolio-kind.mjs`).
+ *
+ * Use the {@link PORTFOLIO_ITEM_KIND} constant for autocomplete-friendly
+ * references. The {@link PortfolioItemKind} type is derived so adding a
+ * member here automatically extends the type.
+ */
+export const PORTFOLIO_ITEM_KIND = {
+    ACCOMPLISHMENT: "accomplishment",
+    BASIC: "basic",
+    CLASSIC: "classic",
+    CODE_BASE: "code_base",
+    OTHER_AMAZING_THINGS: "other_amazing_things",
+};
+/**
+ * Map a portfolio fragment node from the wire shape to the typed
+ * {@link PortfolioItem}. The wire shape carries many more fields (skills,
+ * industries, files, kpis, quotes, details unions) — those are out of
+ * scope for the v0 read surface and dropped here. Callers that need the
+ * extras can issue a richer query in a follow-up.
+ */
+function mapPortfolioNode(node) {
+    const id = node["id"];
+    const skillsConn = node["skills"];
+    const industriesConn = node["industries"];
+    const skills = Array.isArray(skillsConn?.nodes)
+        ? skillsConn.nodes.flatMap((s) => typeof s.id === "string" && typeof s.name === "string" ? [{ id: s.id, name: s.name }] : [])
+        : [];
+    const industries = Array.isArray(industriesConn?.nodes)
+        ? industriesConn.nodes.flatMap((i) => typeof i.id === "string" && typeof i.name === "string" ? [{ id: i.id, name: i.name }] : [])
+        : [];
+    const rawKind = node["kind"];
+    const kind = typeof rawKind === "string" && Object.values(PORTFOLIO_ITEM_KIND).includes(rawKind)
+        ? rawKind
+        : null;
+    return {
+        id: typeof id === "string" ? id : "",
+        title: node["title"] ?? null,
+        description: node["description"] ?? null,
+        link: node["link"] ?? null,
+        highlight: Boolean(node["highlight"]),
+        coverImage: node["coverImage"] ?? null,
+        accomplishment: node["accomplishment"] ?? null,
+        publicationPermit: node["publicationPermit"] ?? null,
+        clientOrCompanyName: node["clientOrCompanyName"] ?? null,
+        websiteUrl: node["websiteUrl"] ?? null,
+        toptalRelated: node["toptalRelated"] ?? null,
+        showViaToptal: node["showViaToptal"] ?? null,
+        kind,
+        skills,
+        industries,
+    };
+}
+/**
+ * Common "200 with errors" shape handler. Returns the unwrapped payload
+ * (the value of the single root data field) as `unknown`; callers
+ * narrow at the call site to their per-operation payload shape. The
+ * helper centralizes the auth-revoked / GraphQL-error / null-data paths
+ * so each operation's domain code stays focused on its own payload
+ * shape.
+ */
+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 PortfolioError("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 PortfolioError("GRAPHQL_ERROR", `${operationName} failed: ${first?.message ?? "GraphQL error"}`);
+    }
+    if (!body?.data) {
+        throw new PortfolioError("UNKNOWN", `${operationName} response had no \`data\` field`);
+    }
+    // The mutation/query operations in this module all use a single root
+    // field whose name matches the operation (createPortfolioItem,
+    // updatePortfolioItem, getPortfolioItems, profile, …). We extract the
+    // single value from `data` here.
+    const keys = Object.keys(body.data);
+    if (keys.length === 0) {
+        throw new PortfolioError("UNKNOWN", `${operationName} response had empty \`data\``);
+    }
+    const firstKey = keys[0];
+    const payload = body.data[firstKey];
+    if (payload === null || payload === undefined) {
+        throw new PortfolioError("UNKNOWN", `${operationName} response had \`null\` payload`);
+    }
+    return payload;
+}
+/** Translate `userErrors[]` into a `USER_ERROR` `PortfolioError`. */
+function rejectIfUserErrors(errors, operationName) {
+    if (Array.isArray(errors) && errors.length > 0) {
+        const first = errors[0];
+        const fieldHint = first?.key ? ` (${first.key})` : "";
+        throw new PortfolioError("USER_ERROR", `${operationName} rejected${fieldHint}: ${first?.message ?? "unknown error"}`);
+    }
+}
+/**
+ * Wrap a transport call, narrowing transport-level errors to
+ * `PortfolioError("NETWORK_ERROR")` while letting `TtctlError` subclasses
+ * (`Cf403Error`, `AuthRevokedError`) bubble up so the CLI/MCP surfaces can
+ * apply uniform recovery presentation.
+ */
+async function withTransportErrors(operationName, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof TtctlError)
+            throw err;
+        if (err instanceof PortfolioError)
+            throw err;
+        throw new PortfolioError("NETWORK_ERROR", `${operationName} request failed: ${err.message}`, {
+            cause: err,
+        });
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*                                Operations                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Full-document `getPortfolioItems` query. Sent against `talent-profile`
+ * (Cloudflare-protected, requires impersonation). Mirrors
+ * `research/graphql/talent_profile/operations/getPortfolioItems.graphql`,
+ * trimmed to the v0 read surface (no skills/industries/files/details
+ * fragments — those are separate sub-domains).
+ */
+/**
+ * Shared selection set for `PortfolioItem` nodes used across `list`,
+ * `create`, `update`, `remove`, `reorder`, and `highlight` mutation
+ * responses. Centralized so the `mapPortfolioNode` mapper always sees a
+ * consistent shape regardless of which operation produced the response.
+ *
+ * Includes `kind`, `skills.nodes`, and `industries.nodes` so the
+ * `update` read-modify-write path can preserve non-null required fields
+ * the server enforces (`showViaToptal`, `skills`).
+ */
+const PORTFOLIO_NODE_SELECTION = `
+  id
+  title
+  description
+  link
+  highlight
+  coverImage
+  accomplishment
+  publicationPermit
+  clientOrCompanyName
+  websiteUrl
+  toptalRelated
+  showViaToptal
+  kind
+  skills { nodes { id name } }
+  industries { nodes { id name } }
+`;
+const GET_PORTFOLIO_ITEMS_QUERY = `query getPortfolioItems($profileId: ID!) {
+  profile(id: $profileId) {
+    id
+    portfolioItems {
+      nodes { ${PORTFOLIO_NODE_SELECTION} }
+    }
+  }
+}`;
+/**
+ * Fetch the signed-in user's portfolio items. Takes the user's auth token
+ * and returns the typed array; the empty-list case returns `[]` (not
+ * `null`).
+ */
+export async function list(token) {
+    const profileId = await extractProfileId(token);
+    // Routed to `talent-profile` (impersonated, Cloudflare-protected): the
+    // older `mobile-gateway` schema is missing fields the read surface
+    // selects (`toptalRelated` empirically — `Cannot query field
+    // "toptalRelated" on type "PortfolioItem"`, captured 2026-05-16). The
+    // talent-profile schema is authoritative for all mutations in this
+    // service; aligning the query surface keeps a single source of truth.
+    const res = await withTransportErrors("getPortfolioItems", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "getPortfolioItems",
+            query: GET_PORTFOLIO_ITEMS_QUERY,
+            variables: { profileId },
+        },
+    }));
+    const profile = unwrapResponse(res, "getPortfolioItems");
+    return profile.portfolioItems.nodes.map(mapPortfolioNode);
+}
+/**
+ * Full-document `createPortfolioItem` mutation. Sent against
+ * `talent-profile`. Returns the freshly-created list so the caller can
+ * surface the new item's id without a second list round-trip.
+ *
+ * **[INFERRED]** Wrapper key `portfolioItem` per Pattern 2 — see
+ * `research/notes/10-mutation-input-patterns.md`. Live-capture this
+ * shape if the server rejects the wrapper.
+ */
+const CREATE_PORTFOLIO_ITEM_MUTATION = `mutation createPortfolioItem($input: CreatePortfolioItemInput!) {
+  createPortfolioItem(input: $input) {
+    profile {
+      id
+      portfolioItems {
+        nodes { ${PORTFOLIO_NODE_SELECTION} }
+      }
+    }
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Default description used when the caller does not supply one. The
+ * server validates a minimum length on `description` (≥200 characters,
+ * empirically discovered during issue #314); a short title-derived
+ * default would be rejected with `"is too short (minimum is 200
+ * characters)"` for typical CLI titles. This placeholder satisfies the
+ * minimum while remaining obviously a placeholder a user would refine.
+ *
+ * Length: 273 characters.
+ */
+const DEFAULT_PORTFOLIO_DESCRIPTION = "This portfolio item was created via the ttctl CLI without an explicit description. " +
+    "Replace this placeholder via `ttctl profile portfolio update <id> --description ...` " +
+    "with details about the project, the work performed, the technologies used, and the outcomes achieved.";
+export async function add(token, input) {
+    if (!input.title || input.title.trim() === "") {
+        throw new PortfolioError("VALIDATION_ERROR", "Portfolio item requires a non-empty `title`.");
+    }
+    // Runtime guard: TS narrowing requires `industryIds` to exist as a
+    // `string[]`, but JS callers / MCP tool inputs / `as any` casts can
+    // bypass that. Server-verified to reject `[]` / `null` / omitted with
+    // `code: blank, key: industries` (live probe 2026-05-16,
+    // `.tmp/probe-empty-industries.mjs`); we surface the same constraint as
+    // VALIDATION_ERROR before reaching the wire.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defense-in-depth for non-TS callers
+    if (!input.industryIds || input.industryIds.length === 0) {
+        throw new PortfolioError("VALIDATION_ERROR", "Portfolio item requires at least one industry id (`industryIds`). " +
+            "Discover catalog IDs via `ttctl profile industries autocomplete <query>`, " +
+            "then pass `--industry-id <id>` (repeatable) on the CLI.");
+    }
+    const profileId = await extractProfileId(token);
+    // The server rejects `skills: []` with `"You need to add at least one
+    // tag"`. When the caller does not supply skills, fall back to the
+    // user's first profile skill — preserves the "minimal CLI invocation
+    // just works" experience and aligns the portfolio entry with the
+    // user's primary skill domain. Empty-profile case surfaces a clear
+    // VALIDATION_ERROR pointing the user at remediation.
+    const callerSkills = input.skills;
+    let resolvedSkills;
+    if (callerSkills !== undefined && callerSkills.length > 0) {
+        resolvedSkills = callerSkills;
+    }
+    else {
+        const profileSkills = await listSkills(token, profileId);
+        if (profileSkills.length === 0) {
+            throw new PortfolioError("VALIDATION_ERROR", "Cannot create portfolio item: profile has no skills. " +
+                "Add at least one skill via `ttctl profile skills add <name>`, " +
+                "then retry — or pass `skills` explicitly.");
+        }
+        // The first skill set is typically the talent's primary skill;
+        // users who want a different tag association can update the item
+        // afterward (or thread `skills` explicitly).
+        const first = profileSkills[0];
+        if (first === undefined) {
+            throw new PortfolioError("UNKNOWN", "Skills list non-empty but indexed lookup returned undefined.");
+        }
+        resolvedSkills = [{ id: first.skill.id, name: first.skill.name }];
+    }
+    const portfolioItem = {
+        kind: PORTFOLIO_ITEM_KIND.BASIC,
+        showViaToptal: true,
+        description: DEFAULT_PORTFOLIO_DESCRIPTION,
+        publicationPermit: true,
+        ...input,
+        // `skills` is set AFTER the spread so the resolved default applies
+        // even when the caller passed an empty array (the server treats `[]`
+        // identically to `null` for this field).
+        skills: resolvedSkills,
+    };
+    const variables = {
+        input: { profileId, portfolioItem },
+    };
+    const res = await withTransportErrors("createPortfolioItem", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "createPortfolioItem",
+            query: CREATE_PORTFOLIO_ITEM_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "createPortfolioItem");
+    rejectIfUserErrors(payload.errors, "createPortfolioItem");
+    if (payload.success === false) {
+        throw new PortfolioError("USER_ERROR", `createPortfolioItem reported success=false${payload.notice ? `: ${payload.notice}` : ""}`);
+    }
+    if (!payload.profile) {
+        throw new PortfolioError("UNKNOWN", "createPortfolioItem succeeded but response had no profile payload.");
+    }
+    return payload.profile.portfolioItems.nodes.map(mapPortfolioNode);
+}
+/**
+ * Full-document `updatePortfolioItem` mutation.
+ *
+ * **[INFERRED]** Wrapper key `portfolioItem` per Pattern 1.
+ */
+const UPDATE_PORTFOLIO_ITEM_MUTATION = `mutation updatePortfolioItem($input: UpdatePortfolioItemInput!) {
+  updatePortfolioItem(input: $input) {
+    profile {
+      id
+      portfolioItems {
+        nodes { ${PORTFOLIO_NODE_SELECTION} }
+      }
+    }
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Update a portfolio item by id. Conceptually a partial update — callers
+ * supply only the fields they want to change — but the server's
+ * `updatePortfolioItem` mutation enforces full-replace semantics on
+ * `PortfolioItemUpdateInput` non-null fields. Verified live 2026-05-16
+ * (probe `.tmp/probe-portfolio-update-shape2.mjs`): the update input
+ * shape DIFFERS from create:
+ *
+ *   - GQL-level non-null required: `showViaToptal`, `skills`.
+ *   - USER_ERROR (`code: blank`) if missing: `description` (≥200 chars),
+ *     `publicationPermit`, `industries` (i.e. `industryIds`).
+ *   - **NOT defined** on `PortfolioItemUpdateInput` (rejected at GQL
+ *     layer): `kind`, `coverImage`. These are write-once on create; to
+ *     change a cover, the caller goes through `uploadCover()` →
+ *     separate mutation, not via `update`.
+ *
+ * To preserve the partial-update UX over the full-replace wire shape,
+ * this function does read-modify-write: fetch the current item, merge
+ * caller's `changes` on top of the current state, then send the merged
+ * input. The mutation response carries the full post-mutation list,
+ * which is returned to callers as `PortfolioItem[]`.
+ *
+ * The function ACCEPTS the broader `PortfolioItemInput` shape (which
+ * still types `kind` / `coverImage`) so callers don't need a separate
+ * partial type, but it INTENTIONALLY DROPS those fields from the merged
+ * payload before sending — keeping them would surface a confusing
+ * "Field is not defined on PortfolioItemUpdateInput" GraphQL error.
+ */
+export async function update(token, id, changes) {
+    if (Object.keys(changes).length === 0) {
+        throw new PortfolioError("VALIDATION_ERROR", "Portfolio update requires at least one field.");
+    }
+    // Read-modify-write: fetch current state of the target item so we can
+    // satisfy the server's non-null requirements on update. `list()` is the
+    // single source of truth for the current shape — using it keeps the
+    // selection-set in sync with `mapPortfolioNode`.
+    const current = (await list(token)).find((it) => it.id === id);
+    if (!current) {
+        throw new PortfolioError("VALIDATION_ERROR", `Portfolio item ${id} not found.`);
+    }
+    // Build the merged input: current state as base, caller's `changes` as
+    // overrides. The wire shape uses `industryIds: string[]` (catalog IDs)
+    // whereas the read shape returns `industries: { id, name }[]` — bridge
+    // by projecting current.industries to ids. Caller's `industryIds`
+    // (when supplied via `changes`) wins over the projected current set.
+    //
+    // Conditional spread is required by `exactOptionalPropertyTypes: true`:
+    // a `T?: string` field cannot be assigned `undefined` (only omitted or
+    // a value), so each potentially-null current field becomes a `&& {...}`
+    // spread that contributes nothing when the current value is null.
+    //
+    // `kind` and `coverImage` are intentionally NOT spread from current —
+    // `PortfolioItemUpdateInput` does not define them. Caller's `changes`
+    // are merged below; we strip these two fields out of the final payload.
+    const merged = {
+        ...(current.title !== null && { title: current.title }),
+        ...(current.description !== null && { description: current.description }),
+        ...(current.link !== null && { link: current.link }),
+        ...(current.websiteUrl !== null && { websiteUrl: current.websiteUrl }),
+        ...(current.accomplishment !== null && { accomplishment: current.accomplishment }),
+        ...(current.publicationPermit !== null && { publicationPermit: current.publicationPermit }),
+        ...(current.clientOrCompanyName !== null && { clientOrCompanyName: current.clientOrCompanyName }),
+        ...(current.toptalRelated !== null && { toptalRelated: current.toptalRelated }),
+        ...(current.showViaToptal !== null && { showViaToptal: current.showViaToptal }),
+        highlight: current.highlight,
+        skills: current.skills,
+        industryIds: current.industries.map((i) => i.id),
+        ...changes,
+    };
+    // Strip the two fields rejected by `PortfolioItemUpdateInput` even if
+    // a caller passed them in `changes` — the typed `PortfolioItemInput`
+    // is shared with `add()` which DOES accept them. Deleting here keeps
+    // the call-site UX uniform: callers can pass `kind` / `coverImage`
+    // through the same typed dict; we'll quietly drop them on the update
+    // path rather than crashing with a server-side GraphQL error.
+    delete merged.kind;
+    delete merged.coverImage;
+    const variables = {
+        input: { portfolioItemId: id, portfolioItem: merged },
+    };
+    const res = await withTransportErrors("updatePortfolioItem", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "updatePortfolioItem",
+            query: UPDATE_PORTFOLIO_ITEM_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "updatePortfolioItem");
+    rejectIfUserErrors(payload.errors, "updatePortfolioItem");
+    if (payload.success === false) {
+        throw new PortfolioError("USER_ERROR", `updatePortfolioItem reported success=false${payload.notice ? `: ${payload.notice}` : ""}`);
+    }
+    if (!payload.profile) {
+        throw new PortfolioError("UNKNOWN", "updatePortfolioItem succeeded but response had no profile payload.");
+    }
+    return payload.profile.portfolioItems.nodes.map(mapPortfolioNode);
+}
+/** Full-document `removePortfolioItem` mutation. Pattern 3 (`Remove<Entity>Input`). */
+const REMOVE_PORTFOLIO_ITEM_MUTATION = `mutation removePortfolioItem($input: RemovePortfolioItemInput!) {
+  removePortfolioItem(input: $input) {
+    profile {
+      id
+      portfolioItems {
+        nodes { ${PORTFOLIO_NODE_SELECTION} }
+      }
+    }
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/** Remove a portfolio item by id. Returns the post-removal list. */
+export async function remove(token, id) {
+    const variables = { input: { portfolioItemId: id } };
+    const res = await withTransportErrors("removePortfolioItem", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "removePortfolioItem",
+            query: REMOVE_PORTFOLIO_ITEM_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "removePortfolioItem");
+    rejectIfUserErrors(payload.errors, "removePortfolioItem");
+    if (!payload.profile) {
+        throw new PortfolioError("UNKNOWN", "removePortfolioItem succeeded but response had no profile payload.");
+    }
+    return payload.profile.portfolioItems.nodes.map(mapPortfolioNode);
+}
+/**
+ * Full-document `changePortfolioItemPosition` mutation. Pattern 5
+ * (`Change<Entity>PositionInput { <entity>Id, position }`).
+ */
+const CHANGE_PORTFOLIO_ITEM_POSITION_MUTATION = `mutation changePortfolioItemPosition($input: ChangePortfolioItemPositionInput!) {
+  changePortfolioItemPosition(input: $input) {
+    profile {
+      id
+      portfolioItems {
+        nodes { ${PORTFOLIO_NODE_SELECTION} }
+      }
+    }
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Reorder portfolio items by setting `id` to the absolute `position`. The
+ * CLI surface translates the more user-friendly `--before <id>` /
+ * `--after <id>` flags to this absolute position; the helpers
+ * {@link positionBefore} / {@link positionAfter} compute the position
+ * given the current list.
+ *
+ * Wire shape (verified live 2026-05-16, probe
+ * `.tmp/probe-portfolio-reorder.mjs`): the position lives INSIDE
+ * `portfolioItem: { position: Int! }` — NOT at the top level of
+ * `ChangePortfolioItemPositionInput`. The naive `{ portfolioItemId,
+ * position }` shape is rejected with "Field is not defined on
+ * ChangePortfolioItemPositionInput" (for `position`) and
+ * "portfolioItem (Expected value to not be null)".
+ */
+export async function reorder(token, id, position) {
+    if (!Number.isInteger(position) || position < 0) {
+        throw new PortfolioError("VALIDATION_ERROR", "Portfolio reorder position must be a non-negative integer.");
+    }
+    const variables = { input: { portfolioItemId: id, portfolioItem: { position } } };
+    const res = await withTransportErrors("changePortfolioItemPosition", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "changePortfolioItemPosition",
+            query: CHANGE_PORTFOLIO_ITEM_POSITION_MUTATION,
+            variables,
+        },
+    }));
+    const payload = unwrapResponse(res, "changePortfolioItemPosition");
+    rejectIfUserErrors(payload.errors, "changePortfolioItemPosition");
+    if (!payload.profile) {
+        throw new PortfolioError("UNKNOWN", "changePortfolioItemPosition succeeded but response had no profile payload.");
+    }
+    return payload.profile.portfolioItems.nodes.map(mapPortfolioNode);
+}
+/**
+ * Compute the absolute position (0-based) the moved item should land at,
+ * given a target item to be placed BEFORE. Returns `null` if `targetId`
+ * is not in the list. The current list is required because the server's
+ * `changePortfolioItemPosition` takes an absolute index, not a relative
+ * one — the CLI computes the index from a friendlier neighbour-anchored
+ * flag.
+ *
+ * Verified live 2026-05-16: the server interprets `position` against the
+ * POST-REMOVAL list (i.e. it first removes the moving item, then inserts
+ * at `position`). Valid range is `[0, N-1]` where `N` is the original
+ * list length; `position = N` (= the naive "after the last item")
+ * returns `USER_ERROR code: invalidPosition` ("Position should be
+ * greater or equal to 0 and less than the number of items").
+ *
+ * When `movingId` is supplied AND points at an item that exists in
+ * `items`, that item is filtered out before computing the target's
+ * index — this correctly handles the case where the moving item is
+ * already in the list and sits before the target (removing it shifts
+ * the target left by 1).
+ */
+export function positionBefore(items, targetId, movingId) {
+    const filtered = movingId !== undefined ? items.filter((it) => it.id !== movingId) : items;
+    const idx = filtered.findIndex((it) => it.id === targetId);
+    return idx === -1 ? null : idx;
+}
+/**
+ * Compute the absolute position the moved item should land at, given a
+ * target item to be placed AFTER. Returns `null` if `targetId` is not in
+ * the list.
+ *
+ * Same post-removal semantics as {@link positionBefore} — pass the
+ * `movingId` so the helper can filter it out of `items` before
+ * computing the target's index. Without `movingId`, the helper assumes
+ * the moving item is not present and computes `idx + 1` directly; that
+ * value will be one too high for the common "move A `--after` B" CLI
+ * flow when both items are in the list and A is before B, and the
+ * server will reject it.
+ */
+export function positionAfter(items, targetId, movingId) {
+    const filtered = movingId !== undefined ? items.filter((it) => it.id !== movingId) : items;
+    const idx = filtered.findIndex((it) => it.id === targetId);
+    return idx === -1 ? null : idx + 1;
+}
+/**
+ * Full-document `highlightPortfolioItem` mutation. Pattern 4
+ * (`Highlight<Entity>Input { <entity>Id, highlight }`). The operation
+ * source-of-truth is `research/graphql/talent_profile/operations/highlightPortfolioItem.graphql`.
+ *
+ * Currently TTCtl exposes a single `highlight <id>` toggle that flips the
+ * highlight state on; un-highlighting via this surface lands as a
+ * follow-up if the use case surfaces.
+ */
+const HIGHLIGHT_PORTFOLIO_ITEM_MUTATION = `mutation highlightPortfolioItem($id: ID!, $highlight: Boolean!) {
+  highlightPortfolioItem(input: { portfolioItemId: $id, highlight: $highlight }) {
+    portfolioItem {
+      id
+      highlight
+    }
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Set or clear the "highlight" flag on a portfolio item. Returns the
+ * minimal `{ id, highlight }` projection from the mutation payload —
+ * fetching the full updated item is a separate `list()` round-trip when
+ * needed.
+ */
+export async function highlight(token, id, flag = true) {
+    const res = await withTransportErrors("highlightPortfolioItem", async () => impersonatedTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "highlightPortfolioItem",
+            query: HIGHLIGHT_PORTFOLIO_ITEM_MUTATION,
+            variables: { id, highlight: flag },
+        },
+    }));
+    const payload = unwrapResponse(res, "highlightPortfolioItem");
+    rejectIfUserErrors(payload.errors, "highlightPortfolioItem");
+    if (!payload.portfolioItem) {
+        throw new PortfolioError("UNKNOWN", "highlightPortfolioItem succeeded but response had no portfolioItem payload.");
+    }
+    return { id: payload.portfolioItem.id, highlight: payload.portfolioItem.highlight };
+}
+/**
+ * Resolve a {@link FileSource} into a {@link MultipartFile} ready for the
+ * multipart body. Path-mode reads the file off disk; buffer-mode is a
+ * pass-through.
+ */
+async function resolveFileSource(source, fieldLabel) {
+    if (source.kind === "buffer") {
+        return {
+            filename: source.filename,
+            content: source.content,
+            ...(source.contentType !== undefined ? { contentType: source.contentType } : {}),
+        };
+    }
+    let content;
+    try {
+        content = await readFile(source.path);
+    }
+    catch (err) {
+        const code = err.code;
+        const message = err instanceof Error ? err.message : String(err);
+        if (code === "ENOENT") {
+            throw new PortfolioError("FILE_NOT_FOUND", `${fieldLabel}: file not found: ${source.path}`);
+        }
+        throw new PortfolioError("FILE_READ_ERROR", `${fieldLabel}: failed to read ${source.path}: ${message}`);
+    }
+    return { filename: basename(source.path), content };
+}
+/**
+ * Full-document `uploadPortfolioCover` mutation. The `file` variable is a
+ * GraphQL `Upload` slot — the multipart map binds it to the
+ * `variables.file` path.
+ *
+ * `transformation` is `PortfolioCoverImageTransformationInput!` with four
+ * non-null `Int!` fields — `cropX`, `cropY`, `cropW`, `cropH` (verified
+ * live 2026-05-16, probe `.tmp/probe-cover-crop.mjs`). Sending `{}` is
+ * rejected at the GQL layer ("Expected value to not be null"). All four
+ * fields must be integers in PIXEL units. The server is tolerant of
+ * oversized crop boxes (e.g. `cropW: 99999`) and will clamp; it does
+ * NOT support normalized 0..1 units.
+ *
+ * The server also enforces a minimum cover-image dimension of
+ * **750 × 500 px** (USER_ERROR `code: invalidImage` —
+ * "This image must be at least 750 x 500px and under 5MB to be
+ * accepted"). Callers are responsible for ensuring the uploaded file
+ * meets this bound; this service does not pre-validate dimensions.
+ */
+const UPLOAD_PORTFOLIO_COVER_MUTATION = `mutation uploadPortfolioCover(
+  $profileId: ID!
+  $transformation: PortfolioCoverImageTransformationInput!
+  $file: Upload!
+) {
+  uploadPortfolioCoverImage(
+    input: { profileId: $profileId, transformation: $transformation, file: $file }
+  ) {
+    coverImageCacheName
+    coverImageUrl
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Read width/height from a PNG file's IHDR chunk. PNG signature is
+ * 8 bytes; the IHDR chunk follows with a 4-byte length, "IHDR" type,
+ * then 4-byte width, 4-byte height (big-endian uint32s). Returns
+ * `null` for non-PNG inputs or short buffers (caller falls back to a
+ * sentinel oversized crop).
+ */
+function parsePngDimensions(buffer) {
+    if (buffer.length < 24)
+        return null;
+    const isPng = buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47 && buffer[4] === 0x0d;
+    if (!isPng)
+        return null;
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const width = view.getUint32(16);
+    const height = view.getUint32(20);
+    if (width <= 0 || height <= 0)
+        return null;
+    return { width, height };
+}
+/**
+ * Upload a cover image for a portfolio item. The cover image is bound to
+ * the user's profile rather than a specific portfolio item — the response
+ * carries a `coverImageCacheName` the caller passes back into a
+ * subsequent `update()` call (or `add()` for new items) via the
+ * `coverImage` field.
+ *
+ * The `transformation` parameter is optional. When omitted, the service
+ * resolves a sensible default: PNG sources have their dimensions read
+ * from the IHDR header and used as the whole-image crop
+ * `(0, 0, width, height)`; non-PNG sources fall back to a large
+ * bounding box `(0, 0, 99999, 99999)` (the server clamps oversized
+ * crops). Callers who need explicit control pass `transformation`
+ * directly.
+ *
+ * The server enforces a minimum cover-image size of 750x500px — the
+ * service does NOT pre-validate this; callers receive a `USER_ERROR`
+ * (`code: invalidImage`) when the image is too small.
+ */
+export async function uploadCover(token, source, transformation) {
+    const profileId = await extractProfileId(token);
+    const file = await resolveFileSource(source, "uploadCover");
+    const resolvedTransformation = transformation ?? defaultCoverTransformation(file.content);
+    const res = await withTransportErrors("uploadPortfolioCover", async () => impersonatedMultipartTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "uploadPortfolioCover",
+            query: UPLOAD_PORTFOLIO_COVER_MUTATION,
+            variables: {
+                profileId,
+                transformation: resolvedTransformation,
+                file: null,
+            },
+        },
+        files: { "0": file },
+        map: { "0": ["variables.file"] },
+    }));
+    const payload = unwrapResponse(res, "uploadPortfolioCover");
+    rejectIfUserErrors(payload.errors, "uploadPortfolioCover");
+    if (payload.success === false) {
+        throw new PortfolioError("USER_ERROR", `uploadPortfolioCover reported success=false${payload.notice ? `: ${payload.notice}` : ""}`);
+    }
+    return {
+        coverImageCacheName: payload.coverImageCacheName ?? null,
+        coverImageUrl: payload.coverImageUrl ?? null,
+    };
+}
+/**
+ * Sentinel oversized crop bounding box used when image dimensions
+ * cannot be statically inferred (non-PNG, malformed PNG). The server
+ * clamps oversized crops to the actual image extent.
+ */
+const OVERSIZED_CROP = { cropX: 0, cropY: 0, cropW: 99999, cropH: 99999 };
+function defaultCoverTransformation(content) {
+    const dims = parsePngDimensions(content);
+    if (dims) {
+        return { cropX: 0, cropY: 0, cropW: dims.width, cropH: dims.height };
+    }
+    return OVERSIZED_CROP;
+}
+/**
+ * Full-document `uploadPortfolioFile` mutation. Variant of `uploadCover`
+ * for arbitrary attachment files (not necessarily images). Same
+ * multipart-map shape; the response carries a `fileCacheName` /
+ * `fileUrl` pair.
+ */
+const UPLOAD_PORTFOLIO_FILE_MUTATION = `mutation uploadPortfolioFile($profileId: ID!, $file: Upload!) {
+  uploadPortfolioFile(input: { profileId: $profileId, file: $file }) {
+    fileCacheName
+    fileUrl
+    success
+    notice
+    errors {
+      code
+      key
+      message
+    }
+  }
+}`;
+/**
+ * Upload a file attachment associated with the user's portfolio. Returns
+ * the cache name + url; the CLI surface prints both for downstream use.
+ */
+export async function uploadFile(token, source) {
+    const profileId = await extractProfileId(token);
+    const file = await resolveFileSource(source, "uploadFile");
+    const res = await withTransportErrors("uploadPortfolioFile", async () => impersonatedMultipartTransport({
+        surface: "talent-profile",
+        authToken: token,
+        body: {
+            operationName: "uploadPortfolioFile",
+            query: UPLOAD_PORTFOLIO_FILE_MUTATION,
+            variables: {
+                profileId,
+                file: null,
+            },
+        },
+        files: { "0": file },
+        map: { "0": ["variables.file"] },
+    }));
+    const payload = unwrapResponse(res, "uploadPortfolioFile");
+    rejectIfUserErrors(payload.errors, "uploadPortfolioFile");
+    if (payload.success === false) {
+        throw new PortfolioError("USER_ERROR", `uploadPortfolioFile reported success=false${payload.notice ? `: ${payload.notice}` : ""}`);
+    }
+    return {
+        fileCacheName: payload.fileCacheName ?? null,
+        fileUrl: payload.fileUrl ?? null,
+    };
+}
+//# sourceMappingURL=index.js.map