Merge pull request #830 from companieshouse/feature/psc-extensions-integration

Psc-Extensions SDK

Author: ehenry27

src/client.ts

@@ -33,6 +33,7 @@ import RegisteredEmailAddressService from "./services/registered-email-address/s
 import { ClientType } from "./enums";
 import { PostcodeLookupService } from "./services/postcode-lookup";
 import PscVerificationService from "./services/psc-verification-link/service";
+import PscExtensionsService from "./services/psc-extensions-link/service";
 import { AccountsFilingService } from "./services/accounts-filing";
 import PscService from "./services/psc/service";
 import { LimitedPartnershipsService } from "./services/limited-partnerships"
@@ -75,6 +76,7 @@ export default class ApiClient {
     public readonly acsp: AcspService;
     public readonly postCodeLookup: PostcodeLookupService;
     public readonly pscVerificationService: PscVerificationService;
+    public readonly pscExtensionsService: PscExtensionsService;
     public readonly accountsFilingService: AccountsFilingService;
     public readonly pscService: PscService;
     public readonly limitedPartnershipsService: LimitedPartnershipsService;
@@ -115,6 +117,7 @@ export default class ApiClient {
         this.transaction = new TransactionService(apiClient);
         this.registeredEmailAddressService = new RegisteredEmailAddressService(apiClient);
         this.postCodeLookup = new PostcodeLookupService(apiClient);
+        this.pscExtensionsService = new PscExtensionsService(apiClient);
         this.pscVerificationService = new PscVerificationService(apiClient);
         this.accountsFilingService = new AccountsFilingService(apiClient);
         this.pscService = new PscService(apiClient);

src/services/psc-extensions-link/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { default as PscExtensionService } from "./service";

src/services/psc-extensions-link/service.ts

@@ -0,0 +1,67 @@
+import { PscExtension, PscExtensionnData } from "./types"
+
+import { Headers, HttpResponse, IHttpClient } from "../../http";
+import Resource, { ApiErrorResponse } from "../resource";
+import Mapping from "../../mapping/mapping";
+import { PersonWithSignificantControlResource } from "../psc/types";
+
+/**
+ * Service class for handling PSC (Person with Significant Control) extension-related operations.
+ * This class provides methods to interact with the PSC extensions API, including creating, retrieving,
+ * and checking the validation of PSC extensions request
+ */
+export default class PscExtensionService {
+    constructor (private readonly client: IHttpClient) {}
+
+    /**
+     * Submits a new PSC extension for a given transaction.
+     *
+     * @param transactionId - The unique identifier of the transaction.
+     * @param pscExtension - The PSC extension data to be submitted.
+     * @returns A promise that resolves to either:
+     * - A `Resource<PscExtension>` object containing the created PSC extension details.
+     * - An `ApiErrorResponse` object if an error occurs during the request.
+     */
+    public async postPscExtension (transactionId: string, pscExtension: PscExtensionnData, headers?: Headers): Promise<Resource<PscExtension> | ApiErrorResponse> {
+        const resourceUri = `/transactions/${transactionId}/persons-with-significant-control-extensions`;
+        const pscExtensionResource = Mapping.snakeCaseKeys(pscExtension);
+        const response = await this.client.httpPost(resourceUri, pscExtensionResource, headers);
+
+        if (response.error) {
+            return this.handleErrorResponse(response);
+        }
+
+        return this.populateFrontEndResource(response);
+    }
+
+    /**
+     * Maps the response body to a front-end resource format with camelCase keys.
+     *
+     * @param response - The HTTP response received from the API.
+     * @returns A `Resource<PscExtension>` object containing the mapped resource.
+     */
+    private populateFrontEndResource (response: HttpResponse): Resource<PscExtension> {
+        const frontEndResource: Resource<PscExtension> = {
+            httpStatusCode: response.status,
+            resource: response.body as PscExtension
+        };
+
+        const body = response.body as PersonWithSignificantControlResource;
+        frontEndResource.resource = Mapping.camelCaseKeys<PscExtension>(body);
+
+        return frontEndResource;
+    }
+
+    /**
+     * Handles error responses from the API by mapping error details to camelCase keys.
+     *
+     * @param response - The HTTP response containing the error details.
+     * @returns An `ApiErrorResponse` object with the mapped error details.
+     */
+    private handleErrorResponse (response: HttpResponse): ApiErrorResponse {
+        return {
+            httpStatusCode: response.status,
+            errors: [Mapping.camelCaseKeys(response.error)]
+        };
+    }
+}

src/services/psc-extensions-link/types.ts

@@ -0,0 +1,148 @@
+export interface PersonWithSignificantControlResource {
+    address: AddressResource,
+    country_of_residence: string,
+    date_of_birth: DateOfBirthResource,
+    ceased_on?: string,
+    etag: string,
+    links: ItemLinksResource,
+    name: string,
+    name_elements: NameElementsResource,
+    nationality: string,
+    natures_of_control: string[],
+    notified_on: string,
+    is_sanctioned?: boolean,
+    kind?: string
+};
+
+export interface PersonWithSignificantControl {
+    address: Address,
+    countryOfResidence: string,
+    dateOfBirth: DateOfBirth,
+    ceasedOn?: string,
+    etag: string,
+    links: ItemLinks,
+    name: string,
+    nameElements: NameElements,
+    nationality: string,
+    naturesOfControl: string[],
+    notifiedOn: string,
+    isSanctioned?: boolean,
+    kind?: string
+};
+
+export interface AddressResource {
+    address_line_1: string;
+    address_line_2?: string;
+    careOf?: string;
+    locality: string;
+    poBox?: string;
+    postal_code?: string;
+    premises?: string;
+    region?: string;
+};
+
+export interface Address {
+    addressLine1: string;
+    addressLine2?: string;
+    careOf?: string;
+    locality: string;
+    poBox?: string;
+    postalCode?: string;
+    premises?: string;
+    region?: string;
+};
+
+export interface DateOfBirthResource {
+    day?: string;
+    month: string;
+    year: string;
+};
+
+export interface DateOfBirth {
+    day?: string;
+    month: string;
+    year: string;
+};
+
+export interface ResultsLinksResource {
+  self: string,
+  persons_with_significant_control_statements_list?: string;
+};
+
+export interface ResultsLinks {
+    self: string,
+    personsWithSignificantControlStatementsList?: string;
+};
+
+export interface ItemLinksResource {
+  self: string,
+  statement?: string;
+};
+
+export interface ItemLinks {
+    self: string,
+    statement?: string;
+};
+
+export interface LinksResource {
+    self: string,
+    validation_status: string
+}
+
+export interface Links {
+    self: string,
+    validationStatus: string
+}
+
+export interface NameElementsResource {
+    forename?: string,
+    other_forenames?: string,
+    middlename?: string,
+    surname?: string,
+    title?: string
+}
+
+export interface NameElements {
+    title?: string;
+    forename?: string;
+    otherForenames?: string;
+    middleName?: string;
+    surname: string;
+};
+
+export interface PscVerificationResource {
+    created_at: Date,
+    updated_at: Date,
+    links: LinksResource,
+    data: PscExtensionnDataResource;
+}
+
+export interface PscExtensionnDataResource {
+    company_number?: string,
+    psc_notification_id?: string,
+    extensionDetails?: ExtensionDetailsResource
+}
+
+export interface PscExtension {
+    createdAt: Date,
+    updatedAt: Date,
+    links: Links,
+    data: PscExtensionnData;
+}
+export interface PscExtensionnData {
+    companyNumber?: string,
+    pscNotificationId?: string,
+    extensionDetails?: ExtensionDetails
+}
+
+export interface ExtensionDetailsResource {
+     extensionReason?: string,
+    nameMismatchReason?: string,
+    extensionRequestDate?: string
+}
+
+export interface ExtensionDetails {
+    extensionReason?: string,
+    nameMismatchReason?: string,
+    extensionRequestDate?: string
+}