Condo Documentation

The Accruals Hub provides three primary functional areas for interacting with utility data:

1. Provider Search: Search for organizations using their INN (Taxpayer Identification Number), name, or other credentials.
2. Accrual Retrieval: Access accrual data via personal accounts (лицевые счета). This returns structured JSON data and includes links to original PDF documents (receipts).
3. Payment Management: Submit payment information, confirm successful transactions, and synchronize payment statuses.

@open-condo/apollo is a wrapper over @apollo/client designed to simplify advanced Apollo Client features. It provides:

• Persistent cache using local storage.
• Configurable Time-To-Live (TTL).
• Cache invalidation utilities.
• A unified configuration pattern that works across getServerSideProps, Server-Side Rendering (SSR), and Client-Side Rendering (CSR).

The Files API is a middleware providing endpoints for uploading binary files and sharing previously uploaded files between different applications or users.

Base path: /api/files

Available Endpoints:

• POST /api/files/upload: Upload one or multiple files. Supports inline attachment to a model in the same request.
• POST /api/files/share: Create a new file record pointing to an existing binary (re-sharing).
• POST /api/files/attach: Attach an existing uploaded file to a specific model record (used if not attached during upload).

Authentication: Endpoints require an authenticated, non-deleted user. Authentication is handled via the app session cookie. Unauthorized or deleted users will receive UNAUTHENTICATED/AUTHORIZATION_REQUIRED errors.

The Accruals Hub provides three primary functional capabilities for managing utility bill data:

1. Find Providers: Search for organizations using TIN (Taxpayer Identification Number), name, or other credentials.
2. Retrieve Accruals: Access billing data using a personal account number. This returns structured JSON data and includes links to original PDF documents (receipts).
3. Manage Payments: Submit payment information, confirm successful transactions, and synchronize payment statuses.

The Condo backend supports authentication via external providers using the Passport.js protocol. The following authorization methods are supported out of the box:

• GitHub: Standard GitHub authentication.
• Generic OpenID Connect provider: Support for any standard OIDC provider.
• OIDC token exchange: A specialized flow where an external frontend provider sends a granular OIDC token, and Condo verifies it using the OIDC userInfo endpoint.

The Dev Portal provides documentation for three primary areas of the Condo ecosystem:

• API Documentation: Detailed information regarding the domain model and the structure of the Condo API.
• Condo UI: Guidance on using the UI kit to build application pages quickly.
• Condo Bridge: Instructions on how to enable mini-applications to interact with the main application.

Once registered as a provider, Condo will issue you a provider name and a client_id.

Authorization Flow

1. Initiate Authorization: Redirect the user to the following endpoint: **/api/auth/:provider?user_type=...&client_id=...&access_token=...**

   • user_type: Use staff for management organization employees or resident for residents.
   • access_token: An OIDC access token issued by your service to allow Condo to fetch user details.

2. Callback: The endpoint will redirect to **/api/auth/:provider/callback** to complete authorization.

3. Success: Upon successful authorization, the user is redirected to **/ and a set-cookie header is issued containing the keystone.sid parameter, which is required for subsequent API requests.

**/api/auth/:provider?user_type=resident&client_id=test-client-id&access_token=YOUR_OIDC_TOKEN**

Instead of a static string, ApolloHelper accepts a function for the uri parameter. This function is executed whenever the client is initialized (via initializeApollo or useApollo), allowing you to resolve the API endpoint dynamically based on the environment (e.g., using relative paths in dev mode and absolute URLs in production/SSR).

const apolloHelper = new ApolloHelper({
    uri: () => {
        if (isDebug() && !isSSR()) {
            return '/api/graphql'
        }
        return `${serviceUrl}/api/graphql`
    },
})