application.ts

/**
 * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
 *
 * WSO2 LLC. licenses this file to you under the Apache License,
 * Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import type {InboundAuthConfig} from './inbound-auth';
import type {AssertionConfig} from './token';

/**
 * Application Response Model (Basic)
 *
 * Basic application information returned in list operations.
 * Contains high-level metadata without detailed configuration.
 *
 * @public
 * @remarks
 * This model is typically returned by GET /applications (list endpoint).
 * For full details including OAuth2 configuration, fetch a specific application by ID.
 *
 * Note: The `clientId` field is included here but doesn't exist in the full `Application` type.
 * It represents the OAuth2 client identifier generated by the server.
 *
 * @example
 * ```typescript
 * // Example response from GET /applications
 * const appList: BasicApplication[] = [
 *   {
 *     id: '550e8400-e29b-41d4-a716-446655440000',
 *     name: 'My Web Application',
 *     description: 'Customer portal application',
 *     clientId: 'myapp_client_id',
 *     logoUrl: 'https://myapp.com/logo.png',
 *     authFlowId: 'edc013d0-e893-4dc0-990c-3e1d203e005b',
 *     registrationFlowId: '80024fb3-29ed-4c33-aa48-8aee5e96d522',
 *     isRegistrationFlowEnabled: true
 *   }
 * ];
 * ```
 */
export type BasicApplication = Pick<
  Application,
  | 'id'
  | 'name'
  | 'description'
  | 'logoUrl'
  | 'authFlowId'
  | 'registrationFlowId'
  | 'isRegistrationFlowEnabled'
  | 'template'
> & {
  /**
   * OAuth2 client identifier
   * Generated by the server for OAuth2/OIDC applications
   * @example 'myapp_client_id'
   */
  clientId?: string;
};

/**
 * Application Response Model (Full)
 *
 * Complete application information including all configuration details.
 * This is the full representation returned when fetching a specific application.
 *
 * @public
 * @remarks
 * This model is returned by:
 * - GET /applications/:id (get by ID)
 * - POST /applications (create)
 * - PUT /applications/:id (update)
 *
 * The response includes:
 * - All basic metadata (name, description, URLs)
 * - Generated identifiers (id, clientId)
 * - Complete OAuth2/OIDC configuration
 * - Timestamps (createdAt, updatedAt)
 *
 * Note: The clientSecret is only returned during creation and is masked in subsequent GET requests.
 *
 * @example
 * ```typescript
 * // Example response from GET /applications/:id
 * const app: Application = {
 *   id: '550e8400-e29b-41d4-a716-446655440000',
 *   name: 'My Web Application',
 *   description: 'Customer portal application',
 *   url: 'https://myapp.com',
 *   logoUrl: 'https://myapp.com/logo.png',
 *   tosUri: 'https://myapp.com/terms',
 *   policyUri: 'https://myapp.com/privacy',
 *   contacts: ['admin@myapp.com'],
 *   authFlowId: 'edc013d0-e893-4dc0-990c-3e1d203e005b',
 *   registrationFlowId: '80024fb3-29ed-4c33-aa48-8aee5e96d522',
 *   isRegistrationFlowEnabled: true,
 *   userAttributes: ['email', 'username'],
 *   inboundAuthConfig: [{
 *     type: 'oauth2',
 *     config: {
 *       clientId: 'myapp_client_id',
 *       clientSecret: '******', // Masked in GET responses
 *       redirectUris: ['https://myapp.com/callback'],
 *       grantTypes: ['authorization_code', 'refresh_token'],
 *       responseTypes: ['code'],
 *       scopes: ['openid', 'profile', 'email'],
 *       token: {
 *         accessToken: {
 *           validityPeriod: 3600,
 *           userAttributes: ['email', 'username']
 *         },
 *         idToken: {
 *           validityPeriod: 3600,
 *           userAttributes: ['sub', 'email', 'name'],
 *           scopeClaims: {
 *             profile: ['name', 'picture'],
 *             email: ['email', 'email_verified']
 *           }
 *         }
 *       }
 *     }
 *   }],
 *   createdAt: '2025-01-15T10:30:00Z',
 *   updatedAt: '2025-01-15T10:30:00Z'
 * };
 * ```
 */
export interface Application {
  /**
   * Unique identifier of the application
   * Generated by the server upon creation
   * @example '550e8400-e29b-41d4-a716-446655440000'
   */
  id: string;

  /**
   * Application name
   * @example 'My Web Application'
   */
  name: string;

  /**
   * Application description
   * @example 'Customer portal application'
   */
  description?: string;

  /**
   * Application URL
   * @example 'https://myapp.example.com'
   */
  url?: string;

  /**
   * Application logo URL
   * @example 'https://myapp.example.com/logo.png'
   */
  logoUrl?: string;

  /**
   * Terms of Service URI
   * @example 'https://myapp.example.com/terms'
   */
  tosUri?: string;

  /**
   * Privacy Policy URI
   * @example 'https://myapp.example.com/privacy'
   */
  policyUri?: string;

  /**
   * Contact email addresses
   * @example ['admin@myapp.example.com', 'support@myapp.example.com']
   */
  contacts?: string[];

  /**
   * Authentication flow ID
   * @example 'edc013d0-e893-4dc0-990c-3e1d203e005b'
   */
  authFlowId?: string;

  /**
   * Registration flow ID
   * @example '80024fb3-29ed-4c33-aa48-8aee5e96d522'
   */
  registrationFlowId?: string;

  /**
   * Whether registration flow is enabled
   * @example true
   */
  isRegistrationFlowEnabled?: boolean;

  /**
   * User attributes to include
   * @example ['email', 'username', 'given_name', 'family_name', 'roles']
   */
  userAttributes?: string[];

  /**
   * Allowed user types (user schema IDs) that can access this application
   * @example ['person', 'person_2', 'person_3']
   */
  allowedUserTypes?: string[];

  /**
   * Theme configuration ID
   * References a theme that customizes the visual styling
   * @example '96c62e6d-9297-4295-8195-d28dfe0c9ff7'
   */
  themeId?: string;

  /**
   * Layout configuration ID
   * References a layout that customizes the screen structure and component positioning
   * @example '96c62e6d-9297-4295-8195-d28dfe0c9ff7'
   */
  layoutId?: string;

  /**
   * Application template identifier
   * Indicates which template was used to create this application
   * @example 'react', 'nextjs', 'browser', 'mobile'
   */
  template?: string;

  /**
   * Inbound authentication configuration
   * Contains OAuth2/OIDC settings
   * Note: clientSecret is masked in GET responses
   * @see InboundAuthConfig
   */
  inboundAuthConfig?: InboundAuthConfig[];

  /**
   * Timestamp when the application was created
   * ISO 8601 format
   * @example '2025-01-15T10:30:00Z'
   */
  createdAt?: string;

  /**
   * Timestamp when the application was last updated
   * ISO 8601 format
   * @example '2025-01-15T14:45:00Z'
   */
  updatedAt?: string;

  /**
   * Additional dynamic properties
   * Allows for extension fields not explicitly defined in the interface
   */
  [key: string]: unknown;

  /**
   * Organization unit ID this application belongs to
   * @example '550e8400-e29b-41d4-a716-446655440000'
   */
  ouId?: string;

  /**
   * Assertion configuration
   * Defines how assertions are generated for this application.
   */
  assertion?: AssertionConfig;
}