@ttctl/core 0.0.0 → 0.1.0-rc.2

package/dist/services/profile/external/index.d.ts

@@ -0,0 +1,278 @@
+import { ProfileError } from "../basic/index.js";
+import type { ProfileErrorCode } from "../basic/index.js";
+export { ProfileError };
+export type { ProfileErrorCode };
+/**
+ * Subset of `UpdateExternalProfilesInput` actually exposed at v0. All fields
+ * are optional; the caller is responsible for passing at least one or the
+ * service will reject with `VALIDATION_ERROR`.
+ *
+ * `twitter / behance / dribbble` are exposed because they are present in the
+ * `UpdateExternalProfilesPayload` response selection of the captured
+ * `UpdateExternalProfiles` mutation document
+ * (`research/graphql/talent_profile/operations/UpdateExternalProfiles.graphql`).
+ * `skype` is also present on the underlying `Profile` type but the captured
+ * mutation document does not request it back; we omit it from the v0 surface
+ * (the user can still update it via the web portal).
+ */
+export interface ExternalProfilesUpdate {
+    linkedin?: string;
+    github?: string;
+    website?: string;
+    twitter?: string;
+    behance?: string;
+    dribbble?: string;
+}
+/**
+ * Server-confirmed result of {@link update}. Mirrors the response selection
+ * of the captured `UpdateExternalProfiles` mutation. Fields are nullable
+ * because the server returns `null` for any external link the talent has
+ * not set.
+ *
+ * `twitter` was added in #345 to close a write-only-echo gap — the input
+ * accepts `twitter` (see {@link ExternalProfilesUpdate}) but the mutation
+ * response previously dropped it, so callers could SET a twitter URL but
+ * not VERIFY it from the response alone (had to issue a follow-up
+ * {@link show} call). Adding it to the selection set + this interface
+ * makes the response self-contained for round-trip verification.
+ */
+export interface UpdateExternalProfilesResult {
+    profile: {
+        id: string;
+        updatedByTalentAt: string | null;
+        linkedin: string | null;
+        github: string | null;
+        website: string | null;
+        twitter: string | null;
+        behance: string | null;
+        dribbble: string | null;
+    };
+    notice: string | null;
+}
+/**
+ * Update external profile URLs (linkedin / github / website / twitter /
+ * behance / dribbble). Each field is optional; the caller must pass at
+ * least one. Unknown / extraneous fields are rejected at compile time by
+ * the {@link ExternalProfilesUpdate} type.
+ *
+ * Wire shape: `{ input: { profileId, profile: { …urls } } }`. Validated
+ * 2026-05-17 via the round-trip E2E at
+ * `packages/e2e/src/42-profile-external-show.e2e.test.ts`. The
+ * previously-inferred `externalProfiles:` wrapper (per Pattern 1 in
+ * `research/notes/10-mutation-input-patterns.md`) was incorrect — same
+ * exception class as `UPDATE_BASIC_INFO` and `updateTimeZoneWorkingHours`,
+ * both of which use `profile:` because they write fields directly on the
+ * Profile entity.
+ *
+ * Errors:
+ *   - `ProfileError("VALIDATION_ERROR")` when no fields are supplied
+ *   - `ProfileError("USER_ERROR")` when the server rejects an individual
+ *     field (e.g. malformed URL)
+ *   - `AuthRevokedError`, `Cf403Error`, other `TtctlError` subclasses
+ *     propagate verbatim
+ */
+export declare function update(token: string, changes: ExternalProfilesUpdate): Promise<UpdateExternalProfilesResult>;
+/**
+ * Boolean trio comprising the talent's onboarding-readiness self-attestation.
+ * All three are exposed unchanged (no display-name remapping) because each
+ * field name is already self-documenting.
+ *
+ * Returned by {@link customRequirementsShow}. Callers willing to accept the
+ * "missing fields default to current state" semantic of
+ * {@link customRequirementsSet} pass a {@link CustomRequirementsUpdate} (a
+ * partial of this trio).
+ */
+export interface CustomRequirements {
+    backgroundCheck: boolean | null;
+    drugTest: boolean | null;
+    timeTrackingTools: boolean | null;
+}
+/**
+ * Read the three onboarding-readiness toggles for the signed-in user.
+ *
+ * Errors: `AuthRevokedError`, `ProfileError(GRAPHQL_ERROR)`,
+ * `ProfileError(NETWORK_ERROR)`, `Cf403Error` (and other `TtctlError`
+ * subclasses) propagate verbatim.
+ */
+export declare function customRequirementsShow(token: string): Promise<CustomRequirements>;
+/**
+ * Partial-update shape for {@link customRequirementsSet}. Each missing
+ * field is filled from the current server state before the mutation is
+ * dispatched (the underlying `updateCustomRequirements` mutation sends ALL
+ * three booleans per call, no PATCH semantics — see the capture notes
+ * referenced in the module comment).
+ */
+export interface CustomRequirementsUpdate {
+    backgroundCheck?: boolean;
+    drugTest?: boolean;
+    timeTrackingTools?: boolean;
+}
+/**
+ * Server-confirmed result of {@link customRequirementsSet}. Mirrors the
+ * response selection of the captured mutation document.
+ */
+export interface CustomRequirementsSetResult {
+    profile: {
+        id: string;
+        updatedByTalentAt: string | null;
+        customRequirements: CustomRequirements;
+    };
+    notice: string | null;
+}
+/**
+ * Toggle one or more of the three onboarding-readiness booleans
+ * (`backgroundCheck`, `drugTest`, `timeTrackingTools`). Caller-omitted
+ * fields are pre-filled from the current server state via
+ * {@link customRequirementsShow} before the mutation is sent (the underlying
+ * `updateCustomRequirements` mutation has no diff/PATCH semantics — every
+ * call resubmits all three booleans).
+ *
+ * Pre-fill of missing fields treats `null` (server has no value yet) as
+ * `false` for the post-merge wire shape, since the mutation input is
+ * `Boolean!` and rejects `null`.
+ *
+ * Errors: same taxonomy as {@link update}.
+ */
+export declare function customRequirementsSet(token: string, changes: CustomRequirementsUpdate): Promise<CustomRequirementsSetResult>;
+/**
+ * The flat boolean set returned by `getProfileReadiness`. Each field
+ * corresponds to a section completion check the platform runs before a
+ * talent can submit-for-review. Schema types each as `Unknown` (the
+ * SDL reflects what we've inferred, not strongly typed) so we coerce
+ * defensively at the boundary.
+ */
+export interface ProfileReadiness {
+    isPhotoResolutionSatisfied: boolean | null;
+    isBasicInfoSatisfied: boolean | null;
+    isCertificationsSatisfied: boolean | null;
+    isEmploymentsCountSatisfied: boolean | null;
+    isEmploymentConnectionsSatisfied: boolean | null;
+    isSkillValidationsSatisfied: boolean | null;
+    isPortfolioItemsCountSatisfied: boolean | null;
+    isPortfolioItemConnectionsSatisfied: boolean | null;
+    isWorkingHoursSatisfied: boolean | null;
+    /**
+     * `submitAvailable` rolls up the per-section signals into a single
+     * "ready to submit?" boolean. Hoisted alongside the per-section
+     * booleans because it's the value the user usually wants at a glance.
+     */
+    submitAvailable: boolean | null;
+    /** ISO timestamp of last talent-side edit, returned by the same query. */
+    updatedByTalentAt: string | null;
+}
+/**
+ * Read the per-section profile-readiness booleans plus the rolled-up
+ * `submitAvailable` flag and the last-edit timestamp.
+ *
+ * Errors: same taxonomy as {@link customRequirementsShow}.
+ */
+export declare function readiness(token: string): Promise<ProfileReadiness>;
+/**
+ * A single recommendation item. The platform returns recommendations as a
+ * union over multiple concrete types
+ * (`EmploymentsCountRecommendation`, `PortfolioItemsCountRecommendation`,
+ * `EmploymentsMissingDataRecommendation`, etc.). We surface the discriminator
+ * `type` plus the entire payload as a generic `payload` map rather than
+ * typing each variant — the per-variant fields are descriptive UX hints, not
+ * enforced data, and the schema types most fields as `Unknown` anyway.
+ * CLI/MCP formatters render `type` and a stringified payload preview;
+ * consumers who need richer typing can extend later.
+ */
+export interface ProfileRecommendation {
+    type: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * Read the list of profile recommendations. Each recommendation has a
+ * discriminator `type` and a small payload of variant-specific fields.
+ *
+ * Recommendations that involve nested entity lists (e.g.
+ * `EmploymentsMissingDataRecommendation` with a `nodes` array of employments)
+ * are intentionally trimmed at the GraphQL level — at v0 the CLI/MCP only
+ * surfaces the recommendation `type` and any scalar variant fields. Drilling
+ * into nested entity lists requires fetching the underlying domain
+ * (employments, portfolio items, skills) directly, which is outside the
+ * recommendations leaf's scope.
+ */
+export declare function recommendations(token: string): Promise<ProfileRecommendation[]>;
+/**
+ * Combined view of the advanced-profile-wizard state. Issue #76 spec collapses
+ * `getAdvancedProfileData` and `GetAdvancedProfileWizardStatus` into a single
+ * read leaf — but `getAdvancedProfileData` already includes
+ * `advancedProfileWizardStatus` in its selection, so a single query suffices.
+ *
+ * `travelVisas` is a list of the talent's submitted travel visas; we surface
+ * a count + the IDs at v0 to keep the payload bounded. Full visa CRUD lives
+ * in the `visas` sub-domain (separate wave).
+ */
+export interface AdvancedProfileSnapshot {
+    /**
+     * Wizard-status discriminator. Schema types as `Unknown`; we surface
+     * whatever the server returns without introspection.
+     */
+    wizardStatus: string | null;
+    travelVisaCount: number;
+    travelVisaIds: string[];
+}
+/**
+ * Read the advanced-profile-wizard status plus a summary of the talent's
+ * travel-visa list. This is the read-side combined view of
+ * `getAdvancedProfileData` — the spec also references
+ * `GetAdvancedProfileWizardStatus` as a separate operation, but
+ * `getAdvancedProfileData` already returns `advancedProfileWizardStatus`, so
+ * one query is sufficient.
+ *
+ * The full TravelVisa fragment is intentionally trimmed to `id` only. Visa
+ * CRUD operations live in the `visas` sub-domain — surfacing the rich shape
+ * here would create a partial duplication that drifts as the visas
+ * sub-domain evolves.
+ */
+export declare function advancedWizardShow(token: string): Promise<AdvancedProfileSnapshot>;
+/**
+ * Server-side state of the talent's external profile URLs. This is the
+ * **read** counterpart of {@link update} — the primary inspection path for
+ * the stored linkedin / github / website / twitter / behance / dribbble
+ * values.
+ *
+ * Prior to this leaf (issue #343) the `external` sub-domain shipped six
+ * service functions but **none** was a primary read for the stored URL
+ * state: `advancedWizardShow` intentionally trims its selection set to
+ * `advancedProfileWizardStatus + travelVisas` (see its doc comment), and
+ * `update`'s response is POST-state only (write-disguised-as-read). This
+ * type closes that asymmetry.
+ *
+ * The shape mirrors what {@link ExternalProfilesUpdate} **accepts** (all
+ * six URL fields), NOT what {@link UpdateExternalProfilesResult} echoes —
+ * the latter drops `twitter` (a separate companion gap on the mutation's
+ * response selection). `show` selects `twitter` directly from the
+ * `Profile` type, so it returns full six-field parity. Every URL is
+ * nullable because the server returns `null` for any link the talent has
+ * not set; `id` / `updatedByTalentAt` mirror the
+ * {@link UpdateExternalProfilesResult.profile} envelope fields.
+ */
+export interface ExternalProfiles {
+    id: string;
+    updatedByTalentAt: string | null;
+    linkedin: string | null;
+    github: string | null;
+    website: string | null;
+    twitter: string | null;
+    behance: string | null;
+    dribbble: string | null;
+}
+/**
+ * Read the talent's stored external profile URLs (linkedin / github /
+ * website / twitter / behance / dribbble) plus `id` and the last
+ * talent-side edit timestamp.
+ *
+ * This is the primary read for the external-URL state — use it instead of
+ * a no-op {@link update} (which is a write-disguised-as-read and risks an
+ * unintended write if the response is misinterpreted).
+ *
+ * Errors: `AuthRevokedError`, `ProfileError(GRAPHQL_ERROR)`,
+ * `ProfileError(NETWORK_ERROR)`, `ProfileError(NO_VIEWER)`, `Cf403Error`
+ * (and other `TtctlError` subclasses) propagate verbatim — same taxonomy
+ * as {@link customRequirementsShow} / {@link readiness}.
+ */
+export declare function show(token: string): Promise<ExternalProfiles>;
+//# sourceMappingURL=index.d.ts.map

package/dist/services/profile/external/index.d.ts.map

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