@poly-x/core 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -630,7 +630,7 @@ var SessionEngine = class {
 			this.applySignOut("expired", true);
 			return;
 		}
-		if (error instanceof UpstreamError || error instanceof Error) this.dispatch({ type: "refresh-failed-transient" });
+		this.dispatch({ type: "refresh-failed-transient" });
 	}
 	async applySignOut(reason, broadcast) {
 		if (this.state.status === "signed-out") return;
@@ -789,6 +789,18 @@ function parseAuthorizeOutcome(status, body) {
 	if (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
 	return { type: "login_required" };
 }
+/**
+* Platform codes that mean "this app is misconfigured", verified against poly-auth
+* `api/constants/auth-responses.ts` and `idp.controller.ts:validateClientAndRedirect`
+* (2026-07-29). Only these map across — an unrecognised 400 keeps the previous
+* behaviour rather than being mislabelled as misconfiguration.
+*/
+const CONFIGURATION_ERROR_CODES = /* @__PURE__ */ new Set([
+	"REDIRECT_URI_NOT_ALLOWED",
+	"INVALID_CLIENT",
+	"KEY_DEPLOYMENT_MISMATCH",
+	"KEY_ENVIRONMENT_MISMATCH"
+]);
 function parsePasswordOutcome(status, body) {
 	const b = asRecord$1(body);
 	const statusField = typeof b.status === "string" ? b.status : void 0;
@@ -809,6 +821,16 @@ function parsePasswordOutcome(status, body) {
 		ticket: typeof b.ticket === "string" ? b.ticket : void 0
 	};
 	if (status === 403) return { type: "no_access" };
+	if (statusField === "verification_required" && typeof b.challengeId === "string") return {
+		type: "verification_required",
+		challengeId: b.challengeId,
+		factorTypes: Array.isArray(b.factorTypes) ? b.factorTypes.filter((f) => typeof f === "string") : []
+	};
+	if (status === 400 && typeof b.code === "string" && CONFIGURATION_ERROR_CODES.has(b.code)) return {
+		type: "configuration_error",
+		code: b.code,
+		message: typeof b.message === "string" ? b.message : void 0
+	};
 	return { type: "invalid_credentials" };
 }
 function parseResetOutcome(status, body) {
@@ -863,6 +885,23 @@ function deriveDisplayName(user) {
 	return displayString([displayString(user.firstName, MAX_DISPLAY_NAME), displayString(user.lastName, MAX_DISPLAY_NAME)].filter(Boolean).join(" "), MAX_DISPLAY_NAME) ?? displayString(user.username, MAX_DISPLAY_NAME) ?? displayString(user.email, MAX_DISPLAY_NAME);
 }
 /**
+* The bounded display subset of a user record: name, email, avatar (ADR-0006).
+*
+* Exported because a profile update has to re-derive exactly these — and only these — after the
+* platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+* re-derivation the display name and avatar are whatever they were at login, forever.
+*
+* Identity and authorization claims are deliberately absent: this returns what is safe to
+* recompute from a profile response, not a whole claim set.
+*/
+function deriveDisplayClaims(user) {
+	return {
+		displayName: deriveDisplayName(user),
+		email: displayString(user.email, MAX_DISPLAY_NAME),
+		avatarUrl: displayString(user.profilePicture, MAX_AVATAR_URL)
+	};
+}
+/**
 * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
 * (ADR-0006); AUTHZ populates roles/permissions later.
 *
@@ -1139,12 +1178,117 @@ var AuthClient = class {
 	}
 };
 //#endregion
+//#region src/profile/validation.ts
+/**
+* Profile input rules (FR-VALID-1…8).
+*
+* These are **mirrored from the platform's own validation** (`poly-auth`
+* `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+* this module accepts must not be one the platform rejects, or a person is shown an error they
+* cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+*
+* The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+* as literals and assert both agree, so a drift fails a build rather than a person's save.
+*/
+/**
+* One or more Unicode letters, optionally joined by a single space, hyphen or apostrophe —
+* "José", "O'Brien", "Anne-Marie", "van der Berg". No digits, no leading/trailing/double
+* separators. (poly-auth `PERSON_NAME_REGEX`.)
+*/
+const PERSON_NAME_REGEX = /^\p{L}+(?:[ '-]\p{L}+)*$/u;
+/** Leading "+", country code starting 1-9, then 7-14 more digits. (poly-auth `E164_PHONE_REGEX`.) */
+const E164_PHONE_REGEX = /^\+[1-9]\d{7,14}$/;
+/** poly-auth's person-name bounds for these two fields (`min: 1, max: 20`). */
+const NAME_MAX = 20;
+/** poly-auth's `imageUpload.middleware` cap. */
+const MAX_PROFILE_IMAGE_BYTES = 50 * 1024 * 1024;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+const PROFILE_FIELDS = [
+	"firstName",
+	"lastName",
+	"phoneNumber",
+	"cnic",
+	"gender"
+];
+function name(value, label) {
+	const trimmed = (value ?? "").trim();
+	if (trimmed === "") return `${label} is required`;
+	if (trimmed.length > NAME_MAX) return `${label} cannot exceed ${NAME_MAX} characters`;
+	if (!PERSON_NAME_REGEX.test(trimmed)) return `${label} may contain only letters, spaces, hyphens and apostrophes`;
+}
+/**
+* Validate a whole draft and report **every** bad field, not the first one.
+*
+* Returning on the first failure would make someone fix one field per attempt — the experience
+* D27 exists to rule out.
+*/
+function validateProfileDraft(draft) {
+	const errors = {};
+	const firstName = name(draft.firstName, "First name");
+	if (firstName) errors.firstName = firstName;
+	const lastName = name(draft.lastName, "Last name");
+	if (lastName) errors.lastName = lastName;
+	const phone = (draft.phoneNumber ?? "").trim();
+	if (phone !== "" && !E164_PHONE_REGEX.test(phone)) errors.phoneNumber = "Phone number must include the country code, e.g. +14155552671";
+	const cnic = (draft.cnic ?? "").trim();
+	if (cnic !== "" && cnic.replace(/\D/g, "") === "") errors.cnic = "National ID must contain digits";
+	return errors;
+}
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+function validateProfileImage(file) {
+	if (!file) return null;
+	if (!file.type.startsWith("image/")) return "Choose an image file";
+	if (file.size > 52428800) return `Image must be smaller than ${Math.round(MAX_PROFILE_IMAGE_BYTES / (1024 * 1024))}MB`;
+	return null;
+}
+/**
+* The changed fields only, trimmed.
+*
+* Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+* fields the person *emptied*. The platform's update applies truthy values only, so an empty
+* one is ignored today — but sending it would mean a future backend that honours empties could
+* blank stored data on a save nobody intended as a deletion.
+*/
+function buildProfileUpdate(draft, stored) {
+	const update = {};
+	for (const field of PROFILE_FIELDS) {
+		const next = (draft[field] ?? "").trim();
+		const current = (stored[field] ?? "").trim();
+		if (next === "" || next === current) continue;
+		update[field] = next;
+	}
+	return update;
+}
+/**
+* poly-auth's fixed conflict messages, mapped to the field each is about.
+*
+* Mirrors `IDENTITY_CONFLICT_MESSAGES` in `poly-auth/src/api/controllers/identity-conflict.util.ts`.
+* The platform reports a uniqueness conflict as a 409 with one of a known set of messages and no
+* machine-readable field, so this is the only way to put the error where the person can act on it
+* (FR-VALID-6) — and matching a fixed enum of strings is a mirror, not a guess at prose.
+*
+* `username` and `email` are absent on purpose: neither is editable here (D25), so there is no
+* field to attach them to and the caller must show them generally rather than drop them.
+*/
+const CONFLICT_MESSAGES = [["an account with this phone number already exists.", "phoneNumber"], ["an account with this cnic already exists.", "cnic"]];
+/**
+* Which editable field a platform conflict message is about, or `null` when it is about something
+* this surface does not edit — or is a message we do not recognise, in which case the caller
+* should show it as a general error. A reworded message degrades to that, rather than breaking.
+*/
+function conflictField(message) {
+	const normalized = (message ?? "").trim().toLowerCase();
+	if (normalized === "") return null;
+	return CONFLICT_MESSAGES.find(([text]) => text === normalized)?.[1] ?? null;
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/core — framework-agnostic guts of the PolyX SDK.
 */
 const PACKAGE_NAME = "@poly-x/core";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+const version = "0.2.0";
 //#endregion
 exports.AuthClient = AuthClient;
 exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
@@ -1157,8 +1301,10 @@ exports.InMemoryLock = InMemoryLock;
 exports.InMemoryPkceStore = InMemoryPkceStore;
 exports.InMemorySessionChannel = InMemorySessionChannel;
 exports.InMemorySessionStore = InMemorySessionStore;
+exports.MAX_PROFILE_IMAGE_BYTES = MAX_PROFILE_IMAGE_BYTES;
 exports.MockTransport = MockTransport;
 exports.PACKAGE_NAME = PACKAGE_NAME;
+exports.PROFILE_FIELDS = PROFILE_FIELDS;
 exports.PolyXConfigError = PolyXConfigError;
 exports.PolyXError = PolyXError;
 exports.RateLimitedError = RateLimitedError;
@@ -1169,9 +1315,12 @@ exports.SystemClock = SystemClock;
 exports.UnauthenticatedError = UnauthenticatedError;
 exports.UpstreamError = UpstreamError;
 exports.ValidationError = ValidationError;
+exports.buildProfileUpdate = buildProfileUpdate;
 exports.computeChallenge = computeChallenge;
+exports.conflictField = conflictField;
 exports.createSessionEngine = createSessionEngine;
 exports.decodeJwtExp = decodeJwtExp;
+exports.deriveDisplayClaims = deriveDisplayClaims;
 exports.generatePkce = generatePkce;
 exports.isTransientStatus = isTransientStatus;
 exports.mapPlatformError = mapPlatformError;
@@ -1185,4 +1334,6 @@ exports.randomState = randomState;
 exports.redactSensitive = redactSensitive;
 exports.reduceSessionState = reduce;
 exports.resolveConfig = resolveConfig;
+exports.validateProfileDraft = validateProfileDraft;
+exports.validateProfileImage = validateProfileImage;
 exports.version = version;

package/dist/index.d.cts

@@ -490,6 +490,34 @@ type PasswordAuthOutcome = {
   ticket?: string;
 } | {
   type: "no_access";
+}
+/**
+ * The credentials were accepted, but the platform wants a second proof of identity
+ * before issuing a session.
+ *
+ * RESERVED, NOT IMPLEMENTED. No deployment produces this today — multi-factor
+ * authentication is a platform release of its own. It is modelled now because the v1
+ * specification claimed the sign-in machine already accommodated a step like this and
+ * it did not: adding the variant later would be a breaking change across three
+ * packages, which is precisely the "flip, not a rebuild" promise that would have been
+ * broken. See the FSD (FR-STEP-1…4).
+ */
+| {
+  type: "verification_required";
+  challengeId: string;
+  factorTypes: readonly string[];
+}
+/**
+ * The APP is misconfigured — not the user's credentials. Reported for an
+ * unregistered `redirect_uri`, an unknown client, or a key bound to another
+ * deployment/environment. Kept separate because collapsing it into
+ * `invalid_credentials` tells a developer with a deployment problem that their
+ * password is wrong, which is exactly what consuming apps had to work around.
+ */
+| {
+  type: "configuration_error";
+  code: string;
+  message?: string;
 };
 declare function parsePasswordOutcome(status: number, body: unknown): PasswordAuthOutcome;
 /**
@@ -503,6 +531,21 @@ declare function parseResetOutcome(status: number, body: unknown): PasswordReset
 //#endregion
 //#region src/auth/normalize.d.ts
 declare function decodeJwtExp(token: string): number | null;
+/**
+ * The bounded display subset of a user record: name, email, avatar (ADR-0006).
+ *
+ * Exported because a profile update has to re-derive exactly these — and only these — after the
+ * platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+ * re-derivation the display name and avatar are whatever they were at login, forever.
+ *
+ * Identity and authorization claims are deliberately absent: this returns what is safe to
+ * recompute from a profile response, not a whole claim set.
+ */
+declare function deriveDisplayClaims(user: Record<string, unknown>): {
+  displayName?: string;
+  email?: string;
+  avatarUrl?: string;
+};
 /**
  * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
  * (ADR-0006); AUTHZ populates roles/permissions later.
@@ -681,11 +724,62 @@ declare class AuthClient {
   private toError;
 }
 //#endregion
+//#region src/profile/validation.d.ts
+/**
+ * Profile input rules (FR-VALID-1…8).
+ *
+ * These are **mirrored from the platform's own validation** (`poly-auth`
+ * `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+ * this module accepts must not be one the platform rejects, or a person is shown an error they
+ * cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+ *
+ * The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+ * as literals and assert both agree, so a drift fails a build rather than a person's save.
+ */
+/** poly-auth's `imageUpload.middleware` cap. */
+declare const MAX_PROFILE_IMAGE_BYTES: number;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+declare const PROFILE_FIELDS: readonly ["firstName", "lastName", "phoneNumber", "cnic", "gender"];
+type ProfileField = (typeof PROFILE_FIELDS)[number];
+type ProfileDraft = Partial<Record<ProfileField, string>>;
+type ProfileErrors = Partial<Record<ProfileField, string>>;
+/** The subset of `File` these rules need, so this stays testable without a DOM. */
+interface ProfileImageLike {
+  type: string;
+  size: number;
+  name?: string;
+}
+/**
+ * Validate a whole draft and report **every** bad field, not the first one.
+ *
+ * Returning on the first failure would make someone fix one field per attempt — the experience
+ * D27 exists to rule out.
+ */
+declare function validateProfileDraft(draft: ProfileDraft): ProfileErrors;
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+declare function validateProfileImage(file: ProfileImageLike | null | undefined): string | null;
+/**
+ * The changed fields only, trimmed.
+ *
+ * Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+ * fields the person *emptied*. The platform's update applies truthy values only, so an empty
+ * one is ignored today — but sending it would mean a future backend that honours empties could
+ * blank stored data on a save nobody intended as a deletion.
+ */
+declare function buildProfileUpdate(draft: ProfileDraft, stored: ProfileDraft): ProfileDraft;
+/**
+ * Which editable field a platform conflict message is about, or `null` when it is about something
+ * this surface does not edit — or is a message we do not recognise, in which case the caller
+ * should show it as a general error. A reworded message degrades to that, rather than breaking.
+ */
+declare function conflictField(message: string | undefined | null): ProfileField | null;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/core — framework-agnostic guts of the PolyX SDK.
  */
 declare const PACKAGE_NAME = "@poly-x/core";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, type MockRoute, MockTransport, PACKAGE_NAME, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, UnauthenticatedError, UpstreamError, ValidationError, computeChallenge, createSessionEngine, decodeJwtExp, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, version };
+export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, MAX_PROFILE_IMAGE_BYTES, type MockRoute, MockTransport, PACKAGE_NAME, PROFILE_FIELDS, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, type ProfileDraft, type ProfileErrors, type ProfileField, type ProfileImageLike, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, UnauthenticatedError, UpstreamError, ValidationError, buildProfileUpdate, computeChallenge, conflictField, createSessionEngine, decodeJwtExp, deriveDisplayClaims, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, validateProfileDraft, validateProfileImage, version };

package/dist/index.d.mts

@@ -490,6 +490,34 @@ type PasswordAuthOutcome = {
   ticket?: string;
 } | {
   type: "no_access";
+}
+/**
+ * The credentials were accepted, but the platform wants a second proof of identity
+ * before issuing a session.
+ *
+ * RESERVED, NOT IMPLEMENTED. No deployment produces this today — multi-factor
+ * authentication is a platform release of its own. It is modelled now because the v1
+ * specification claimed the sign-in machine already accommodated a step like this and
+ * it did not: adding the variant later would be a breaking change across three
+ * packages, which is precisely the "flip, not a rebuild" promise that would have been
+ * broken. See the FSD (FR-STEP-1…4).
+ */
+| {
+  type: "verification_required";
+  challengeId: string;
+  factorTypes: readonly string[];
+}
+/**
+ * The APP is misconfigured — not the user's credentials. Reported for an
+ * unregistered `redirect_uri`, an unknown client, or a key bound to another
+ * deployment/environment. Kept separate because collapsing it into
+ * `invalid_credentials` tells a developer with a deployment problem that their
+ * password is wrong, which is exactly what consuming apps had to work around.
+ */
+| {
+  type: "configuration_error";
+  code: string;
+  message?: string;
 };
 declare function parsePasswordOutcome(status: number, body: unknown): PasswordAuthOutcome;
 /**
@@ -503,6 +531,21 @@ declare function parseResetOutcome(status: number, body: unknown): PasswordReset
 //#endregion
 //#region src/auth/normalize.d.ts
 declare function decodeJwtExp(token: string): number | null;
+/**
+ * The bounded display subset of a user record: name, email, avatar (ADR-0006).
+ *
+ * Exported because a profile update has to re-derive exactly these — and only these — after the
+ * platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+ * re-derivation the display name and avatar are whatever they were at login, forever.
+ *
+ * Identity and authorization claims are deliberately absent: this returns what is safe to
+ * recompute from a profile response, not a whole claim set.
+ */
+declare function deriveDisplayClaims(user: Record<string, unknown>): {
+  displayName?: string;
+  email?: string;
+  avatarUrl?: string;
+};
 /**
  * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
  * (ADR-0006); AUTHZ populates roles/permissions later.
@@ -681,11 +724,62 @@ declare class AuthClient {
   private toError;
 }
 //#endregion
+//#region src/profile/validation.d.ts
+/**
+ * Profile input rules (FR-VALID-1…8).
+ *
+ * These are **mirrored from the platform's own validation** (`poly-auth`
+ * `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+ * this module accepts must not be one the platform rejects, or a person is shown an error they
+ * cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+ *
+ * The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+ * as literals and assert both agree, so a drift fails a build rather than a person's save.
+ */
+/** poly-auth's `imageUpload.middleware` cap. */
+declare const MAX_PROFILE_IMAGE_BYTES: number;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+declare const PROFILE_FIELDS: readonly ["firstName", "lastName", "phoneNumber", "cnic", "gender"];
+type ProfileField = (typeof PROFILE_FIELDS)[number];
+type ProfileDraft = Partial<Record<ProfileField, string>>;
+type ProfileErrors = Partial<Record<ProfileField, string>>;
+/** The subset of `File` these rules need, so this stays testable without a DOM. */
+interface ProfileImageLike {
+  type: string;
+  size: number;
+  name?: string;
+}
+/**
+ * Validate a whole draft and report **every** bad field, not the first one.
+ *
+ * Returning on the first failure would make someone fix one field per attempt — the experience
+ * D27 exists to rule out.
+ */
+declare function validateProfileDraft(draft: ProfileDraft): ProfileErrors;
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+declare function validateProfileImage(file: ProfileImageLike | null | undefined): string | null;
+/**
+ * The changed fields only, trimmed.
+ *
+ * Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+ * fields the person *emptied*. The platform's update applies truthy values only, so an empty
+ * one is ignored today — but sending it would mean a future backend that honours empties could
+ * blank stored data on a save nobody intended as a deletion.
+ */
+declare function buildProfileUpdate(draft: ProfileDraft, stored: ProfileDraft): ProfileDraft;
+/**
+ * Which editable field a platform conflict message is about, or `null` when it is about something
+ * this surface does not edit — or is a message we do not recognise, in which case the caller
+ * should show it as a general error. A reworded message degrades to that, rather than breaking.
+ */
+declare function conflictField(message: string | undefined | null): ProfileField | null;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/core — framework-agnostic guts of the PolyX SDK.
  */
 declare const PACKAGE_NAME = "@poly-x/core";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, type MockRoute, MockTransport, PACKAGE_NAME, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, UnauthenticatedError, UpstreamError, ValidationError, computeChallenge, createSessionEngine, decodeJwtExp, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, version };
+export { AuthClient, type AuthClientOptions, type AuthorizeOutcome, type AuthorizeWithPasswordParams, type BrandingTokens, type BuildAuthorizeUrlParams, type Clock, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, type ExchangeCodeParams, type FetchBrandingParams, FetchTransport, type FieldError, ForbiddenError, type HttpMethod, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, type KeyEnv, type KeyKind, type Lock, MAX_PROFILE_IMAGE_BYTES, type MockRoute, MockTransport, PACKAGE_NAME, PROFILE_FIELDS, type ParsedKey, type PasswordAuthOutcome, type PasswordResetOutcome, type PkceEntry, type PkcePair, type PkceStore, type PlatformResponseLike, PolyXConfigError, PolyXError, type PolyXErrorOptions, type ProfileDraft, type ProfileErrors, type ProfileField, type ProfileImageLike, RateLimitedError, type RefreshTokens, type ResolveConfigInput, type ResolvedConfig, type RetryPolicy, type RuntimeContext, type Session, type SessionChannel, type SessionChannelEvent, type SessionClaims, SessionEngine, type SessionEngineOptions, type SessionEvent, SessionExpiredError, SessionRevokedError, type SessionState, type SessionStore, type SetPasswordParams, type SignedOutReason, type StoredSession, SystemClock, type TenantOption, type TimerHandle, type TokenSet, type Transport, type TransportRequest, type TransportResponse, UnauthenticatedError, UpstreamError, ValidationError, buildProfileUpdate, computeChallenge, conflictField, createSessionEngine, decodeJwtExp, deriveDisplayClaims, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, validateProfileDraft, validateProfileImage, version };

package/dist/index.mjs

@@ -629,7 +629,7 @@ var SessionEngine = class {
 			this.applySignOut("expired", true);
 			return;
 		}
-		if (error instanceof UpstreamError || error instanceof Error) this.dispatch({ type: "refresh-failed-transient" });
+		this.dispatch({ type: "refresh-failed-transient" });
 	}
 	async applySignOut(reason, broadcast) {
 		if (this.state.status === "signed-out") return;
@@ -788,6 +788,18 @@ function parseAuthorizeOutcome(status, body) {
 	if (statusField === "login_required" || b.code === "LOGIN_REQUIRED") return { type: "login_required" };
 	return { type: "login_required" };
 }
+/**
+* Platform codes that mean "this app is misconfigured", verified against poly-auth
+* `api/constants/auth-responses.ts` and `idp.controller.ts:validateClientAndRedirect`
+* (2026-07-29). Only these map across — an unrecognised 400 keeps the previous
+* behaviour rather than being mislabelled as misconfiguration.
+*/
+const CONFIGURATION_ERROR_CODES = /* @__PURE__ */ new Set([
+	"REDIRECT_URI_NOT_ALLOWED",
+	"INVALID_CLIENT",
+	"KEY_DEPLOYMENT_MISMATCH",
+	"KEY_ENVIRONMENT_MISMATCH"
+]);
 function parsePasswordOutcome(status, body) {
 	const b = asRecord$1(body);
 	const statusField = typeof b.status === "string" ? b.status : void 0;
@@ -808,6 +820,16 @@ function parsePasswordOutcome(status, body) {
 		ticket: typeof b.ticket === "string" ? b.ticket : void 0
 	};
 	if (status === 403) return { type: "no_access" };
+	if (statusField === "verification_required" && typeof b.challengeId === "string") return {
+		type: "verification_required",
+		challengeId: b.challengeId,
+		factorTypes: Array.isArray(b.factorTypes) ? b.factorTypes.filter((f) => typeof f === "string") : []
+	};
+	if (status === 400 && typeof b.code === "string" && CONFIGURATION_ERROR_CODES.has(b.code)) return {
+		type: "configuration_error",
+		code: b.code,
+		message: typeof b.message === "string" ? b.message : void 0
+	};
 	return { type: "invalid_credentials" };
 }
 function parseResetOutcome(status, body) {
@@ -862,6 +884,23 @@ function deriveDisplayName(user) {
 	return displayString([displayString(user.firstName, MAX_DISPLAY_NAME), displayString(user.lastName, MAX_DISPLAY_NAME)].filter(Boolean).join(" "), MAX_DISPLAY_NAME) ?? displayString(user.username, MAX_DISPLAY_NAME) ?? displayString(user.email, MAX_DISPLAY_NAME);
 }
 /**
+* The bounded display subset of a user record: name, email, avatar (ADR-0006).
+*
+* Exported because a profile update has to re-derive exactly these — and only these — after the
+* platform saves. `normalizeRefresh` carries claims forward unchanged, so without a deliberate
+* re-derivation the display name and avatar are whatever they were at login, forever.
+*
+* Identity and authorization claims are deliberately absent: this returns what is safe to
+* recompute from a profile response, not a whole claim set.
+*/
+function deriveDisplayClaims(user) {
+	return {
+		displayName: deriveDisplayName(user),
+		email: displayString(user.email, MAX_DISPLAY_NAME),
+		avatarUrl: displayString(user.profilePicture, MAX_AVATAR_URL)
+	};
+}
+/**
 * `POST /idp/token` → StoredSession. Claims carry identity plus the bounded display subset
 * (ADR-0006); AUTHZ populates roles/permissions later.
 *
@@ -1138,11 +1177,116 @@ var AuthClient = class {
 	}
 };
 //#endregion
+//#region src/profile/validation.ts
+/**
+* Profile input rules (FR-VALID-1…8).
+*
+* These are **mirrored from the platform's own validation** (`poly-auth`
+* `src/api/validations/common-fields.ts`), not invented here. That is the whole point: a value
+* this module accepts must not be one the platform rejects, or a person is shown an error they
+* cannot act on — and the error arrives after a round trip, attached to nothing in particular.
+*
+* The mirroring is the fragile part. It is pinned by tests that restate the platform's patterns
+* as literals and assert both agree, so a drift fails a build rather than a person's save.
+*/
+/**
+* One or more Unicode letters, optionally joined by a single space, hyphen or apostrophe —
+* "José", "O'Brien", "Anne-Marie", "van der Berg". No digits, no leading/trailing/double
+* separators. (poly-auth `PERSON_NAME_REGEX`.)
+*/
+const PERSON_NAME_REGEX = /^\p{L}+(?:[ '-]\p{L}+)*$/u;
+/** Leading "+", country code starting 1-9, then 7-14 more digits. (poly-auth `E164_PHONE_REGEX`.) */
+const E164_PHONE_REGEX = /^\+[1-9]\d{7,14}$/;
+/** poly-auth's person-name bounds for these two fields (`min: 1, max: 20`). */
+const NAME_MAX = 20;
+/** poly-auth's `imageUpload.middleware` cap. */
+const MAX_PROFILE_IMAGE_BYTES = 50 * 1024 * 1024;
+/** The text fields this release makes editable (FR-PROF-4 / D25). */
+const PROFILE_FIELDS = [
+	"firstName",
+	"lastName",
+	"phoneNumber",
+	"cnic",
+	"gender"
+];
+function name(value, label) {
+	const trimmed = (value ?? "").trim();
+	if (trimmed === "") return `${label} is required`;
+	if (trimmed.length > NAME_MAX) return `${label} cannot exceed ${NAME_MAX} characters`;
+	if (!PERSON_NAME_REGEX.test(trimmed)) return `${label} may contain only letters, spaces, hyphens and apostrophes`;
+}
+/**
+* Validate a whole draft and report **every** bad field, not the first one.
+*
+* Returning on the first failure would make someone fix one field per attempt — the experience
+* D27 exists to rule out.
+*/
+function validateProfileDraft(draft) {
+	const errors = {};
+	const firstName = name(draft.firstName, "First name");
+	if (firstName) errors.firstName = firstName;
+	const lastName = name(draft.lastName, "Last name");
+	if (lastName) errors.lastName = lastName;
+	const phone = (draft.phoneNumber ?? "").trim();
+	if (phone !== "" && !E164_PHONE_REGEX.test(phone)) errors.phoneNumber = "Phone number must include the country code, e.g. +14155552671";
+	const cnic = (draft.cnic ?? "").trim();
+	if (cnic !== "" && cnic.replace(/\D/g, "") === "") errors.cnic = "National ID must contain digits";
+	return errors;
+}
+/** `null` when the file is acceptable (or absent — a photo is optional). */
+function validateProfileImage(file) {
+	if (!file) return null;
+	if (!file.type.startsWith("image/")) return "Choose an image file";
+	if (file.size > 52428800) return `Image must be smaller than ${Math.round(MAX_PROFILE_IMAGE_BYTES / (1024 * 1024))}MB`;
+	return null;
+}
+/**
+* The changed fields only, trimmed.
+*
+* Two deliberate exclusions: unchanged fields (so an untouched save is a no-op, FR-PROF-7) and
+* fields the person *emptied*. The platform's update applies truthy values only, so an empty
+* one is ignored today — but sending it would mean a future backend that honours empties could
+* blank stored data on a save nobody intended as a deletion.
+*/
+function buildProfileUpdate(draft, stored) {
+	const update = {};
+	for (const field of PROFILE_FIELDS) {
+		const next = (draft[field] ?? "").trim();
+		const current = (stored[field] ?? "").trim();
+		if (next === "" || next === current) continue;
+		update[field] = next;
+	}
+	return update;
+}
+/**
+* poly-auth's fixed conflict messages, mapped to the field each is about.
+*
+* Mirrors `IDENTITY_CONFLICT_MESSAGES` in `poly-auth/src/api/controllers/identity-conflict.util.ts`.
+* The platform reports a uniqueness conflict as a 409 with one of a known set of messages and no
+* machine-readable field, so this is the only way to put the error where the person can act on it
+* (FR-VALID-6) — and matching a fixed enum of strings is a mirror, not a guess at prose.
+*
+* `username` and `email` are absent on purpose: neither is editable here (D25), so there is no
+* field to attach them to and the caller must show them generally rather than drop them.
+*/
+const CONFLICT_MESSAGES = [["an account with this phone number already exists.", "phoneNumber"], ["an account with this cnic already exists.", "cnic"]];
+/**
+* Which editable field a platform conflict message is about, or `null` when it is about something
+* this surface does not edit — or is a message we do not recognise, in which case the caller
+* should show it as a general error. A reworded message degrades to that, rather than breaking.
+*/
+function conflictField(message) {
+	const normalized = (message ?? "").trim().toLowerCase();
+	if (normalized === "") return null;
+	return CONFLICT_MESSAGES.find(([text]) => text === normalized)?.[1] ?? null;
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/core — framework-agnostic guts of the PolyX SDK.
 */
 const PACKAGE_NAME = "@poly-x/core";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+const version = "0.2.0";
 //#endregion
-export { AuthClient, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, FetchTransport, ForbiddenError, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, MockTransport, PACKAGE_NAME, PolyXConfigError, PolyXError, RateLimitedError, SessionEngine, SessionExpiredError, SessionRevokedError, SystemClock, UnauthenticatedError, UpstreamError, ValidationError, computeChallenge, createSessionEngine, decodeJwtExp, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, version };
+export { AuthClient, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_MS, ENDPOINTS, FetchTransport, ForbiddenError, INITIAL_STATE as INITIAL_SESSION_STATE, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, MAX_PROFILE_IMAGE_BYTES, MockTransport, PACKAGE_NAME, PROFILE_FIELDS, PolyXConfigError, PolyXError, RateLimitedError, SessionEngine, SessionExpiredError, SessionRevokedError, SystemClock, UnauthenticatedError, UpstreamError, ValidationError, buildProfileUpdate, computeChallenge, conflictField, createSessionEngine, decodeJwtExp, deriveDisplayClaims, generatePkce, isTransientStatus, mapPlatformError, normalizeExchange, normalizeRefresh, parseAuthorizeOutcome, parsePasswordOutcome, parsePolyXKey, parseResetOutcome, randomState, redactSensitive, reduce as reduceSessionState, resolveConfig, validateProfileDraft, validateProfileImage, version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Framework-agnostic core of the PolyX SDK",
   "license": "MIT",
   "type": "module",