// The published type declarations for this package.
//
// Handwritten and self-contained on purpose: the implementation re-exports
// from private workspace packages an npm consumer cannot resolve, and the
// repo's TypeScript (tsgo) has no declaration bundler that could inline
// them. src/declaration-sync.ts static-asserts this surface against the
// implementation, so drift fails the typecheck instead of shipping.
//
// The react-JSX element typings (<x-signed-in> in TSX) still live in the
// private core package and are not declared here; issue ISS-0058's augmentation
// reaches workspace consumers only. Declaring it for npm consumers needs a
// react type dependency and its own decision.

interface LogoConfig {
  src?: string
  currentColor?: string
}

interface FaviconConfig {
  src?: string
}

interface AvatarConfig {
  collection?: string
  src?: string
  count?: number
  initials?: boolean
  icon?: boolean
  background?: string
  color?: string
}

/**
 * One themed design block. `theme` is the label: 'auto' is the base every
 * theme deep-merges over; 'light' and 'dark' override it field by field.
 */
interface DesignConfig {
  theme?: string
  primary?: string
  favicon?: FaviconConfig
  logo?: LogoConfig
  avatar?: AvatarConfig
}

interface SignInConfig {
  enabled: boolean
  factors?: string[]
  alternative?: string[]
  mfa?: string[]
}

interface SignUpConfig {
  enabled: boolean
  factor?: string
  ask?: string[]
}

interface AppConfig {
  url?: string
  name?: string
  linkExpiry?: number
  linkExpiryStr?: string
}

/** The flow config as the backend serves it from `/api/flow/config`. */
interface FlowConfig {
  /** Forces 'light' or 'dark'; absent (or 'auto') follows the browser. */
  theme?: string
  design?: DesignConfig[]
  signIn?: SignInConfig
  signUp?: SignUpConfig
  /** Enabled social connector ids, in display order; absent means none. */
  social?: string[]
  app?: AppConfig
  /** Origin uploaded images are served from; absent when the instance hosts none. */
  assets?: string
}

interface UserData {
  id: string
  accountId: string
  accountName: string
  name: string
  email: string
  role: string
  status: string
  picture: string
  pictureAlt: number
  createdAt?: string
  updatedAt?: string
  lastSignIn?: string
}

interface EmailAddressData {
  email: string
  verified: boolean
  via: string
  status: string
  verifiedAt?: string
  createdAt?: string
  updatedAt?: string
}

interface SessionInfoData {
  id: string
  expiresAt?: string
  createdAt?: string
  authenticatedAt?: string
}

interface SessionData {
  session?: SessionInfoData
  identity?: Partial<UserData>
  emailAddresses?: EmailAddressData[]
  redirectTo?: string
}

/** The few facts a settings section carries; the client derives the affordance from them. */
interface SectionState {
  passwordSet?: boolean
  /** Whether the account holds an address; the password offer is gated on it. */
  hasEmail?: boolean
  linked?: string[]
}

/** One entry of the settings index. `id` names the section; its label, icon and form stay client-side. */
interface SettingsSection {
  id: string
  group: 'personal' | 'workspace'
  state?: SectionState
}

/** Which settings sections this viewer gets, in display order. A section they do not get is absent. */
interface SettingsIndex {
  sections: SettingsSection[]
}

/** One linked social identity. */
interface Connection {
  provider: string
  email?: string
  name?: string
  connectedAt?: string
}

/** What asset ingest answers with. */
interface AssetUpload {
  id: string
  contentType: string
  size: number
  width: number
  height: number
}

/** The data surface the components read; an alternative implementation can be installed through `ContextOptions.api`. */
interface Api {
  fetchSession: () => Promise<SessionData>
  fetchUsers: () => Promise<UserData[]>
  updateUserRole: (args: { userId: string; role: string }) => Promise<unknown>
  updateProfile: (args: { userId: string; name?: string; picture?: string }) => Promise<unknown>
  /** Uploads one image and answers its content-addressed identifier; the same picture twice yields the same id. */
  uploadAsset: (file: File) => Promise<AssetUpload>
  deleteUser: (args: { userId: string }) => Promise<unknown>
  inviteUser: (args: { email: string }) => Promise<unknown>
  fetchSettingsIndex: () => Promise<SettingsIndex>
  changePassword: (args: { oldPassword: string; newPassword: string }) => Promise<unknown>
  setPassword: () => Promise<unknown>
  fetchConnections: () => Promise<{ connections: Connection[] }>
  /** Answers where to send the browser to connect the provider; no url means it was done in place (demo API). */
  linkConnection: (args: { provider: string; redirectUri?: string }) => Promise<{ url?: string }>
  unlinkConnection: (args: { provider: string }) => Promise<unknown>
}

/** The flow surface (sign-in, sign-up, OTP); an alternative implementation can be installed through `ContextOptions.flowApi`. */
interface FlowApi {
  signIn: (data?: unknown) => Promise<unknown>
  signUp: (data?: unknown) => Promise<unknown>
  resetPassword: (args: { email: string }) => Promise<unknown>
  updatePassword: (args: { password: string }) => Promise<unknown>
  fetchConfig: () => Promise<unknown>
  confirmCode: (data?: unknown) => Promise<unknown>
}

interface ContextOptions {
  baseUrl: string
  cors: boolean
  shadow: boolean
  autoLogin: boolean
  debugHttp?: boolean
  config?: FlowConfig
  /** An alternative API implementation; unset means the HTTP client. */
  api?: Api
  /** Same seam for the flow endpoints (sign-in, sign-up, OTP); unset means HTTP. */
  flowApi?: FlowApi
}

interface TokenResponse {
  token: string
  [key: string]: unknown
}

/**
 * The owned token contract, identical to the one the React SDK publishes:
 * resolves the JWT, or null when there is no session, and rejects only on a
 * real failure.
 */
export declare function getToken(): Promise<string | null>

/**
 * @deprecated Use {@link getToken} instead, removed in 2.0.0.
 *
 * Returns core's `{ token, ... }` response and rejects with an `APIError` on a
 * 401, so being signed out arrives as a thrown error rather than a value. That
 * is the disagreement with the React SDK this export exists to stop spreading.
 */
export declare function fetchToken(): Promise<TokenResponse>

/**
 * Configures the SDK and registers the custom elements; nothing renders until
 * it has run.
 */
export declare function configureUserspace(opts?: Partial<ContextOptions>): Promise<void>

/**
 * Opens the shared settings popup. One popup instance serves every caller,
 * including every `<x-trigger action="settings">`. Without an active session
 * it warns on the console and opens nothing.
 */
export declare function openSettings(): Promise<void>

/** Opens the settings popup on a named section (e.g. `'connections'`); absent, the first one. */
export declare function openSettingsAt(section?: string): Promise<void>

/** The fragment that opens the settings popup on a section: append it to a URL a round trip should return to, or link it directly. */
export declare function settingsFragment(section: string): string

/** Reads the settings marker off the current URL, opens the popup there, and strips it. `configureUserspace` calls this for you. */
export declare function resumeSettings(): void

/**
 * Registers the custom elements without configuring the SDK — for hosts that
 * configure another way, like the React SDK's provider. Idempotent.
 */
export declare function registerElements(options?: { shadow?: boolean }): void

export interface SignInOptions {
  /**
   * Where to land once the session starts. Defaults to the current URL, so the
   * user returns where they were; a page that hands the visitor off elsewhere
   * — a marketing site sending them into the app — names its target. The
   * server validates it against the tenant's allowlist and falls back to the
   * app URL, so an untrusted value is ignored rather than honored.
   */
  redirectUri?: string
}

/**
 * Leaves for the hosted sign-in page, carrying `redirect_uri` back to the
 * current URL — or to `redirectUri` — so the user lands where they belong.
 * The imperative counterpart of `autoLogin`'s redirect, and the same action
 * every `<x-trigger action="sign-in">` fires.
 */
export declare const signIn: (options?: SignInOptions) => void

/**
 * Signs the user out and navigates away: POSTs to the sign-out endpoint, then
 * leaves for `redirectUri` — an absolute URL whose origin the tenant's
 * allowlist must trust, validated server-side — or the hosted sign-in page
 * when the option is absent or untrusted. Ends every session in this browser,
 * not only the current one: the server terminates the whole cookie-scoped
 * session, so other tabs are signed out too. Same action every
 * `<x-trigger action="sign-out">` fires.
 */
export interface SignOutOptions {
  /**
   * Where to land after sign-out: an absolute URL on an origin the tenant's
   * allowlist trusts. The server validates it; an untrusted value degrades to
   * the sign-in page rather than becoming an open redirect.
   */
  redirectUri?: string
}

export declare const signOut: (options?: SignOutOptions) => Promise<void>

/** The custom element tags `configureUserspace` registers. */
export type UserspaceTagName =
  | 'x-authorized'
  | 'x-signed-in'
  | 'x-non-authorized'
  | 'x-signed-out'
  | 'x-button'
  | 'x-badge'
  | 'x-users'
  | 'x-profile-settings'
  | 'x-change-password'
  | 'x-connected-accounts'
  | 'x-settings'
  | 'x-portal'
  | 'x-signin-button'
  | 'x-signout-button'
  | 'x-trigger'

declare global {
  /** Both builds also expose the API here, for a page that cannot use modules. */
  var Userspace: {
    configureUserspace: typeof configureUserspace
    getToken: typeof getToken
    fetchToken: typeof fetchToken
    openSettings: typeof openSettings
    registerElements: typeof registerElements
    signIn: typeof signIn
    signOut: typeof signOut
  }

  interface HTMLElementTagNameMap {
    'x-authorized': HTMLElement
    'x-signed-in': HTMLElement
    'x-non-authorized': HTMLElement
    'x-signed-out': HTMLElement
    'x-button': HTMLElement
    'x-badge': HTMLElement
    'x-users': HTMLElement
    'x-profile-settings': HTMLElement
    'x-change-password': HTMLElement
    'x-connected-accounts': HTMLElement
    'x-settings': HTMLElement
    'x-portal': HTMLElement
    'x-signin-button': HTMLElement
    'x-signout-button': HTMLElement
    'x-trigger': HTMLElement
  }
}