Wire path aliases if you moved files:

{
  "compilerOptions": {
    "paths": {
      "@idp/*": ["src/idp/*"]
    }
  }
}

Public API

ExtendedError

import { ExtendedError } from './src/idp/errors';

class ExtendedError extends Error {
  values: Record<string, unknown> | undefined;
  constructor(message: string, values?: Record<string, unknown>);
}

Use ExtendedError when you need to attach structured interpolation values to an error (e.g., HTTP status codes, state strings) that will later be rendered by ErrorMessageComponent. Pass values as the second argument; they are merged with any values on the message descriptor during rendering.

ERROR_* constants

import {
  ERROR_LOGIN_VALIDATE_MISSINGUSERNAME,
  ERROR_LOGIN_VALIDATE_MISSINGPASSWORD,
  ERROR_LOGIN_FAILED,
  ERROR_HTTP_NETWORK_ERROR,
  ERROR_HTTP_UNEXPECTED_RESPONSE_STATUS,
  ERROR_HTTP_UNEXPECTED_RESPONSE_STATE,
} from './src/idp/errors';

// All are string constants, e.g.:
// ERROR_LOGIN_FAILED === 'konnect.error.login.failed'

Use these constants as error identifiers in Redux actions or thrown ExtendedError instances. They are matched inside ErrorMessageComponent to produce translated human-readable messages. Never hard-code the string values; always import the constant.

ErrorMessageComponent (default-exported via withTranslation)

import { ErrorMessageComponent } from './src/idp/errors';

// Props:
// error: Error | ExtendedError | { id?: string; message: string; values?: object }
// values?: Record<string, unknown>   (merged on top of error.values)
// t: TFunction  (injected by react-i18next HOC wrapping)

Render this component inside any form that produces login or HTTP errors. It handles all known konnect.error.* keys and falls back to a raw translation call for unknown messages. Wrap it with withTranslation from react-i18next before use, or use the already-wrapped export.

Working examples

Scenario - Rendering the Login screen standalone

Embed the Login container in an existing React app without the full index.tsx bootstrap.

import React from 'react';
import { Provider } from 'react-redux';
import store from './src/idp/store';
import Loginscreen from './src/idp/containers/Login';

export function IDPLoginPage() {
  return (
    <Provider store={store as any}>
      <Loginscreen />
    </Provider>
  );
}

Scenario - Displaying a translated error after a failed login attempt

Use ExtendedError and ERROR_LOGIN_FAILED to create a typed error, then render it via ErrorMessageComponent.

import React from 'react';
import { withTranslation, useTranslation } from 'react-i18next';
import { ExtendedError, ERROR_LOGIN_FAILED, ErrorMessageComponent } from './src/idp/errors';

const TranslatedError = withTranslation()(ErrorMessageComponent);

export function LoginForm() {
  const [error, setError] = React.useState<ExtendedError | null>(null);

  const handleSubmit = async () => {
    try {
      // simulate a failed login
      throw new ExtendedError(ERROR_LOGIN_FAILED);
    } catch (e) {
      setError(e as ExtendedError);
    }
  };

  return (
    <div>
      <button onClick={handleSubmit}>Login</button>
      {error && <TranslatedError error={error} />}
    </div>
  );
}

Scenario - Handling an unexpected HTTP response status error

import React from 'react';
import { withTranslation } from 'react-i18next';
import {
  ExtendedError,
  ERROR_HTTP_UNEXPECTED_RESPONSE_STATUS,
  ErrorMessageComponent,
} from './src/idp/errors';

const TranslatedError = withTranslation()(ErrorMessageComponent);

async function fetchToken(): Promise<void> {
  const res = await fetch('/konnect/v1/token');
  if (res.status !== 200) {
    throw new ExtendedError(ERROR_HTTP_UNEXPECTED_RESPONSE_STATUS, { status: res.status });
  }
}

export function TokenButton() {
  const [err, setErr] = React.useState<ExtendedError | null>(null);

  return (
    <div>
      <button onClick={() => fetchToken().catch(setErr)}>Get Token</button>
      {err && <TranslatedError error={err} />}
    </div>
  );
}

File walkthrough

• services/idp/src/index.tsx - Bootstraps React into #root, reads data-bg-img attribute, wraps app in Redux Provider and React.StrictMode.
• services/idp/src/containers/Login/index.js - Re-exports Loginscreen; the primary credential entry UI shown during an OIDC authorization request.
• services/idp/src/containers/Welcome/index.js - Re-exports Welcomescreen; shown after successful authentication/consent.
• services/idp/src/containers/Goodbye/index.js - Re-exports Goodbyescreen; shown after logout or session termination.
• services/idp/src/errors/index.js - Exports all error constants, ExtendedError, and the i18n-aware ErrorMessageComponent. Central location for all IDP error handling.

Common pitfalls and fixes

• document.getElementById('root') returns null: Ensure your HTML has <div id="root"></div> before the script executes, or defer the script tag.
• withTranslation wrapping is required on ErrorMessageComponent: The component uses t as a prop injected by the HOC; importing and rendering it directly without withTranslation() will throw a "t is not a function" error.
• Redux store typed as any: store is passed as store as any in index.tsx; if you have strict Redux typings, provide your own typed store or cast explicitly.
• i18n not initialized before first render: ./i18n is imported as a side-effect in index.tsx; if you split the app, ensure the i18n import is at the top of your own entry file before any component renders.
• ESM/CJS interop with prop-types: If bundling with Rollup or a strict ESM setup, add prop-types to your external list or ensure your bundler handles CommonJS interop (@rollup/plugin-commonjs).
• Background image attribute ignored: data-bg-img must be set on the element with id="root", not on <body> or a wrapper; the code reads it specifically via root.getAttribute('data-bg-img').

Vibe-coding prompt template

I have the OpenCloud backend IDP frontend source in `source/services/idp/src/`.
The USAGE.md file in the same directory contains full integration instructions.

Please help me integrate this into my existing React/TypeScript project step by step:

1. Read USAGE.md and the file excerpts under `source/services/idp/src/` to understand
   the real exports: ExtendedError, ERROR_* constants, ErrorMessageComponent,
   and the Login/Welcome/Goodbye screen containers.

2. Install all required npm dependencies listed in USAGE.md.

3. Embed the Login container into my existing `src/pages/LoginPage.tsx`, wrapping
   it with the Redux Provider using the store from `source/services/idp/src/store`.

4. Wire up `ErrorMessageComponent` (via `withTranslation`) to display translated
   login errors using the `ERROR_LOGIN_FAILED` and `ERROR_HTTP_NETWORK_ERROR` constants.

5. Ensure `i18n` is initialized (side-effect import) before any IDP component renders.

6. Show me the final `LoginPage.tsx` and any changes needed to `tsconfig.json`.

Do not invent any exports; use only what is documented in USAGE.md and visible in source/.

License and credit

The OpenCloud backend server is released under the Apache 2.0 License. See source/LICENSE for the full text. Upstream project: opencloud-eu/opencloud on GitHub.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。