@reapit/gbl-pp-owner-api-ts-definitions 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# gbl-pp-owner-api-ts-definitions
+
+TypeScript type definitions for the PayProp Owner API.
+
+## Installation
+
+```sh
+yarn add @reapit/gbl-pp-owner-api-ts-definitions
+```
+
+## Usage
+
+```ts
+import type {
+  AgencyModel,
+  AgenciesPagedResult,
+} from "@reapit/gbl-pp-owner-api-ts-definitions";
+```
+
+All types are exported from the package root. Hover over any property in your editor to see its JSDoc description sourced directly from the API schema.
+
+## API Reference
+
+- **Owner API docs:** [https://ukapi.staging.payprop.com/api/docs/owner](https://ukapi.staging.payprop.com/api/docs/owner)
+- **Owner API user docs:** [http://one-portal-schema-ppza-128675916895.s3-website.eu-west-1.amazonaws.com/](http://one-portal-schema-ppza-128675916895.s3-website.eu-west-1.amazonaws.com/)
+
+## Available Types
+
+| Type                          | Description                                           |
+| ----------------------------- | ----------------------------------------------------- |
+| `AgencyModel`                 | Full agency entity                                    |
+| `AgenciesPagedResult`         | Paginated response from `GET /agencies`               |
+| `AgenciesInvoicesModel`       | Agency invoice item                                   |
+| `AgenciesInvoicesPagedResult` | Paginated response from `GET /agencies/invoices`      |
+| `AttachmentModel`             | File attachment                                       |
+| `AttachmentsPagedResult`      | Paginated response from `GET /attachments/{source}`   |
+| `BeneficiaryModel`            | Full beneficiary entity                               |
+| `BeneficiariesPagedResult`    | Paginated response from `GET /beneficiaries`          |
+| `PropertyModel`               | Full property entity                                  |
+| `PropertiesPagedResult`       | Paginated response from `GET /properties`             |
+| `PaymentsIncomingModel`       | Incoming payment item                                 |
+| `PaymentsIncomingPagedResult` | Paginated response from `GET /payments/incoming`      |
+| `PaymentsOutgoingModel`       | Outgoing payment item                                 |
+| `PaymentsOutgoingPagedResult` | Paginated response from `GET /payments/outgoing`      |
+| `PaymentsCombinedModel`       | Combined incoming/outgoing payment item               |
+| `PaymentsCombinedPagedResult` | Paginated response from `GET /payments/combined`      |
+| `PaymentsSummaryModel`        | Payment summary response from `GET /payments/summary` |
+| `PaymentBatchModel`           | Outgoing batch payment information                    |
+| `PaymentsOutgoingOriginModel` | Individual payment origin entry                       |
+| `OwnershipModel`              | Ownership record                                      |
+| `OwnershipsPagedResult`       | Paginated response from `GET /ownerships`             |
+| `TenantModel`                 | Full tenant entity                                    |
+| `TenantsPagedResult`          | Paginated response from `GET /tenants`                |
+| `TenantsBalancesModel`        | Tenant balance item                                   |
+| `TenantsBalancesPagedResult`  | Paginated response from `GET /tenants/balances`       |
+| `TenantsTenanciesModel`       | Tenancy record                                        |
+| `TenantsTenanciesPagedResult` | Paginated response from `GET /tenants/tenancies`      |
+| `PaginationModel`             | Pagination metadata                                   |
+| `AddressModel`                | Address entity                                        |
+| `ErrorResponseModel`          | Standard API error response                           |
+| `ErrorItemModel`              | Individual error item                                 |
+
+### User API
+
+| Type                              | Description                                                                |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `UserModel`                       | Full user response (Cognito user + metadata)                               |
+| `UserCognitoModel`                | Cognito user object from `AdminCreateUserCommand`                          |
+| `UserCognitoAttributeModel`       | Individual Cognito user attribute (name/value pair)                        |
+| `UserRoleModel`                   | User role enum (`owner` \| `tenant`)                                       |
+| `PublicMetadataModel`             | Metadata payload for `GET`/`PUT /public/metadata` (owner, tenant, or both) |
+| `OwnerMetadataModel`              | Owner-specific metadata                                                    |
+| `TenantMetadataModel`             | Tenant-specific metadata                                                   |
+| `UserAddressModel`                | Address associated with a user                                             |
+| `UserUpdateRequestModel`          | Request body for `PUT /private/users`                                      |
+| `UserCreateRequestModel`          | Request body for `POST /private/users` (owner or tenant union)             |
+| `UserCreateOwnerRequestModel`     | Request body for `POST /private/users` when creating an owner              |
+| `UserCreateTenantRequestModel`    | Request body for `POST /private/users` when creating a tenant              |
+| `SendOwnerInvitationRequestModel` | Request body for `POST /private/send-owner-invitation`                     |
+| `SendOwnerInvitationItemModel`    | Single invitation entry (requires `id` or `email`)                         |
+| `SendOwnerInvitationModel`        | Response from `POST /private/send-owner-invitation`                        |

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types/shared";
+export * from "./types/agency";
+export * from "./types/attachment";
+export * from "./types/beneficiaries";
+export * from "./types/properties";
+export * from "./types/payment";
+export * from "./types/ownership";
+export * from "./types/tenant";
+export * from "./types/user";
+export * from "./types/error";

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/shared"), exports);
+__exportStar(require("./types/agency"), exports);
+__exportStar(require("./types/attachment"), exports);
+__exportStar(require("./types/beneficiaries"), exports);
+__exportStar(require("./types/properties"), exports);
+__exportStar(require("./types/payment"), exports);
+__exportStar(require("./types/ownership"), exports);
+__exportStar(require("./types/tenant"), exports);
+__exportStar(require("./types/user"), exports);
+__exportStar(require("./types/error"), exports);

package/dist/types/agency.d.ts

@@ -0,0 +1,91 @@
+import type { AddressModel, AgencyBasicModel, AmountBase, DateStringNullable, ExternalID, PaginationModel, PropertyBasicModel } from "./shared";
+/**
+ * Full agency entity. Contains all agency details including contact information.
+ */
+export interface AgencyModel {
+    /** Agency contact details. */
+    contact_details: {
+        /** Address associated with the agency. */
+        address: AddressModel;
+        /** Email address. */
+        email: string;
+        /** Fax number. */
+        fax: string;
+        /** Phone number. */
+        phone: string;
+    };
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Indicates if the agency is active on PayProp. */
+    is_active: boolean;
+    /** URL of the agency logo image. */
+    logo: string;
+    /** Agency name. */
+    name: string;
+    /** Number of unique properties related to beneficiaries under the current agency. */
+    number_of_properties: number;
+    /** Agency registration number. */
+    registration_number: string;
+    /**
+     * Agency termination date.
+     * Relevant only when `is_active` field value is `false`.
+     */
+    termination_date: DateStringNullable;
+    /** Agency VAT number. */
+    vat_number: string;
+    /** Agency website address. */
+    website: string;
+}
+/**
+ * Paginated response from `GET /agencies`.
+ */
+export interface AgenciesPagedResult {
+    /** List of agency entities. */
+    items: AgencyModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}
+/**
+ * Agency invoice item. Represents an outgoing payment made by the agency
+ * and the associated property and payment record.
+ */
+export interface AgenciesInvoicesModel {
+    /** Minimal information about the agency this invoice belongs to. */
+    agency: AgencyBasicModel;
+    /** PayProp external ID of the invoice. */
+    id: ExternalID;
+    /** Invoice number on the statement. */
+    invoice_number: number;
+    /**
+     * Outgoing payment instruction associated with this invoice.
+     * In cases where the outgoing payment originated from the system this field will be `null`.
+     */
+    payment_instruction: {
+        /** Description of the payment instruction. */
+        description: string;
+        /** PayProp external ID of the payment instruction. */
+        id: ExternalID;
+    } | null;
+    /** Outgoing payment record associated with the agency invoice number. */
+    payment_record: {
+        /** Payment record amount. */
+        amount: AmountBase;
+        /** PayProp external ID of the payment record. */
+        id: ExternalID;
+        /** Date the payment was released, or null if not yet released. */
+        release_date: DateStringNullable;
+        /** Tax amount on the payment record. */
+        tax_amount: AmountBase;
+    };
+    /** Minimal information about the property associated with this invoice. */
+    property: PropertyBasicModel;
+}
+/**
+ * Paginated response from `GET /agencies/invoices`.
+ */
+export interface AgenciesInvoicesPagedResult {
+    /** List of agency invoice items. */
+    items: AgenciesInvoicesModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}

package/dist/types/agency.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/attachment.d.ts

@@ -0,0 +1,29 @@
+import type { ExternalID, PaginationModel } from "./shared";
+/**
+ * A file attachment linked to a payment or other resource.
+ */
+export interface AttachmentModel {
+    /** PayProp external ID of the attachment. */
+    id: ExternalID;
+    /** File name. */
+    name: string;
+    /** File size in bytes. */
+    size: number;
+    /**
+     * Timestamp when the file was uploaded.
+     * Format: `YYYY-MM-DD HH:mm:ss`
+     * @example '2022-07-25 11:44:36'
+     */
+    timestamp: string;
+    /** File type / extension. */
+    type: string;
+}
+/**
+ * Paginated response from `GET /attachments/{source}`.
+ */
+export interface AttachmentsPagedResult {
+    /** List of attachment items. */
+    items: AttachmentModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}

package/dist/types/attachment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/beneficiaries.d.ts

@@ -0,0 +1,32 @@
+import type { AddressModel, AgencyBasicModel, ExternalID, PaginationModel } from "./shared";
+/**
+ * Full beneficiary entity. Contains all beneficiary details including
+ * address and ownership information.
+ */
+export interface BeneficiaryModel {
+    /** Address associated with the beneficiary. */
+    address: AddressModel;
+    /** Minimal information about the agency associated with this beneficiary. */
+    agency: AgencyBasicModel;
+    /** Business name. */
+    business_name: string;
+    /** Formatted beneficiary display name used on the platform. */
+    display_name: string;
+    /** Beneficiary first name. */
+    first_name: string;
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Beneficiary last name. */
+    last_name: string;
+    /** Number of unique properties the beneficiary has an ownership. */
+    number_of_properties: number;
+}
+/**
+ * Paginated response from `GET /beneficiaries`.
+ */
+export interface BeneficiariesPagedResult {
+    /** List of beneficiary entities. */
+    items: BeneficiaryModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}

package/dist/types/beneficiaries.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * An individual error item returned in API error responses.
+ */
+export interface ErrorItemModel {
+    /** Descriptive error message. */
+    message: string;
+    /** Optional field path that caused the error. */
+    path: string | null;
+}
+/**
+ * Standard error response returned by the API on non-2xx responses.
+ */
+export interface ErrorResponseModel {
+    /** List of error details. */
+    errors: ErrorItemModel[];
+    /** HTTP response status code. */
+    status: number;
+}

package/dist/types/error.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/ownership.d.ts

@@ -0,0 +1,34 @@
+import type { AgencyBasicModel, AmountBase, BeneficiaryBasicModel, DateString, DateStringNullable, ExternalID, PaginationModel, PropertyBasicModel } from "./shared";
+/**
+ * Ownership record linking a beneficiary to a property for a specific date range.
+ *
+ * Note: multiple ownership records may exist for the same property and beneficiary
+ * combination due to different start and end date periods.
+ */
+export interface OwnershipModel {
+    /** Minimal information about the agency managing the property. */
+    agency: AgencyBasicModel;
+    /** Minimal information about the beneficiary who holds this ownership. */
+    beneficiary: BeneficiaryBasicModel;
+    /** Ownership end date. `null` if the ownership is open-ended (no end date). */
+    end_date: DateStringNullable;
+    /** PayProp external ID of this ownership record. */
+    id: ExternalID;
+    /** Whether the ownership is currently active based on its start and end dates. */
+    is_active: boolean;
+    /** The beneficiary's ownership percentage of the property. */
+    percentage: AmountBase;
+    /** Minimal information about the property this ownership is associated with. */
+    property: PropertyBasicModel;
+    /** Ownership start date. */
+    start_date: DateString;
+}
+/**
+ * Paginated response from `GET /ownerships`.
+ */
+export interface OwnershipsPagedResult {
+    /** List of ownership records. */
+    items: OwnershipModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}

package/dist/types/ownership.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/payment.d.ts

@@ -0,0 +1,383 @@
+import type { AgencyBasicModel, AmountBase, DateString, ExternalID, PaginationModel, PropertyBasicModel, TenantBasicModel } from "./shared";
+/**
+ * Outgoing batch payment information.
+ * Every outgoing payment belongs to a batch. If the batch amount equals the payment
+ * amount, there is only a single payment in the batch for that property.
+ */
+export interface PaymentBatchModel {
+    /**
+     * Outgoing payment batch amount.
+     *
+     * This batch amount can represent a larger total paid to the target beneficiary if there
+     * are multiple payments for the same date and property. If the batch amount equals the
+     * payment amount, there is only a single payment in the batch for this property.
+     */
+    amount: AmountBase;
+}
+/**
+ * An individual origin entry that contributed funds to a grouped outgoing payment.
+ */
+export interface PaymentsOutgoingOriginModel {
+    /**
+     * The channel through which the incoming funds were received.
+     *
+     * - `apa` - APA
+     * - `ozow` - Ozow
+     * - `pay_at` - Pay@
+     * - `lockbox` - Lockbox
+     * - `truelayer` - TrueLayer
+     * - `gocardless` - GoCardless
+     * - `tenant_portal` - Tenant Portal
+     * - `direct_deposit` - Direct deposit
+     * - `bank_debit_order` - Bank debit order
+     * - `transfer_from_damage_deposit` - Transfer from damage deposit
+     * - `transfer_from_property_account` - Transfer from property account
+     * - `unknown` - Unmapped account type
+     */
+    account_type: "apa" | "ozow" | "pay_at" | "lockbox" | "truelayer" | "gocardless" | "tenant_portal" | "direct_deposit" | "bank_debit_order" | "transfer_from_damage_deposit" | "transfer_from_property_account" | "unknown";
+    /** Amount contributed by this payment origin. */
+    amount: AmountBase;
+    /** PayProp external ID of the payment origin. */
+    id: ExternalID;
+    /**
+     * Minimal info about the tenant associated with this origin.
+     *
+     * Will be `null` when the incoming funds originated from system sources
+     * (e.g. property account) rather than a specific tenant.
+     */
+    tenant: TenantBasicModel | null;
+    /**
+     * Transaction type based on the incoming payment origin.
+     *
+     * - `payment` - Standard incoming payment
+     * - `debit_note` - Debit note
+     * - `posted_payment` - Posted payment
+     * - `payment_prop_acc` - Payment from property account
+     * - `deposit_repayment` - Release from deposit account
+     * - `unknown` - Unmapped transaction type
+     */
+    transaction_type: "payment" | "debit_note" | "posted_payment" | "payment_prop_acc" | "deposit_repayment" | "unknown";
+}
+/**
+ * Individual incoming payment from the "Money in" section.
+ */
+export interface PaymentsIncomingModel {
+    /** Minimal information about the agency associated with this payment. */
+    agency: AgencyBasicModel;
+    /** Incoming payment amount. */
+    amount: AmountBase;
+    /**
+     * Incoming payment category.
+     * Only relevant where `transaction_type` is `"invoice"`.
+     */
+    category: {
+        /** PayProp external ID of the category. */
+        id?: ExternalID;
+        /** Category name. */
+        name?: string;
+    } | null;
+    /**
+     * Incoming payment description.
+     * Only relevant where `transaction_type` is `"invoice"`.
+     */
+    description: string | null;
+    /**
+     * Indicates if the invoice has tax enabled.
+     * Only relevant where `transaction_type` is `"invoice"`.
+     */
+    has_tax: boolean;
+    /** PayProp external ID of this incoming payment. */
+    id: ExternalID;
+    /** Minimal information about the property this payment is associated with. */
+    property: PropertyBasicModel;
+    /** Date the incoming payment was reconciled against the property. */
+    reconciliation_date: DateString;
+    /**
+     * Incoming payment tax amount.
+     * Only relevant where `transaction_type` is `"invoice"`.
+     */
+    tax_amount: AmountBase;
+    /**
+     * Minimal info about the tenant associated with this payment.
+     *
+     * Will be `null` when the incoming transaction did not originate from a tenant directly,
+     * such as a payment from property account (`payment_prop_acc`).
+     */
+    tenant: TenantBasicModel | null;
+    /**
+     * Incoming payment transaction type.
+     *
+     * - `invoice` – Platform invoice raised against a tenant and property. These entries **do not** represent an incoming transaction.
+     * - `payment` – Standard incoming transaction.
+     * - `payment_prop_acc` – Transaction released from property account.
+     * - `deposit_repayment` – Transaction released from deposit account.
+     * - `unknown` – Unmapped payment type.
+     */
+    transaction_type: "invoice" | "payment" | "payment_prop_acc" | "deposit_repayment" | "unknown";
+}
+/**
+ * Paginated response from `GET /payments/incoming`.
+ */
+export interface PaymentsIncomingPagedResult {
+    /** List of incoming payment items. */
+    items: PaymentsIncomingModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}
+/**
+ * Outgoing payment item from the "Money out" section.
+ *
+ * Outgoing payments are grouped by transaction date, category, payment target and property.
+ * Payments originating from damage deposit releases or property accounts are always individual items.
+ */
+export interface PaymentsOutgoingModel {
+    /** Minimal information about the agency associated with this payment. */
+    agency: AgencyBasicModel;
+    /** Total outgoing payment amount for this grouped entry. */
+    amount: AmountBase;
+    /** Information about file attachments and the relevant payment rule IDs. */
+    attachments: {
+        /** Indicates if the outgoing payment has any attachments assigned to original payment split rules. */
+        has_attachments: boolean;
+        /** List of payment rule IDs that compose the outgoing payment and have one or more attachments. */
+        payment_ids: ExternalID[];
+    };
+    /** Outgoing payment category. */
+    category: {
+        /** PayProp external ID of the category. */
+        id: ExternalID;
+        /** Outgoing payment category name. */
+        name: string;
+    };
+    /** Outgoing payment instruction description. */
+    description: string;
+    /**
+     * Indicates if at least one of the grouped outgoing payments has tax enabled.
+     *
+     * Note: a payment can have a tax amount of `0.00` and still have this flag set to `true`.
+     */
+    has_tax: boolean;
+    /**
+     * List of grouped outgoing payment record IDs that compose this entry.
+     *
+     * **This list may be incomplete** if a certain threshold of payment items is reached.
+     * Compare the length of this array against `number_of_payments` to verify completeness.
+     */
+    ids: ExternalID[];
+    /** Number of individual payment origins this grouped outgoing payment consists of. */
+    number_of_payment_origins: number;
+    /** Number of individual payment records this grouped outgoing payment consists of. */
+    number_of_payments: number;
+    /** Outgoing batch payment information. */
+    payment_batch: PaymentBatchModel;
+    /**
+     * List of payment origins that contributed funds to this grouped outgoing payment.
+     *
+     * **This list may be incomplete** if a certain threshold is reached.
+     * Compare the length of this array against `number_of_payment_origins` to verify completeness.
+     */
+    payment_origins: PaymentsOutgoingOriginModel[];
+    /** Outgoing payment beneficiary (recipient). */
+    payment_target: {
+        /** PayProp external ID of the beneficiary. */
+        id: ExternalID;
+        /** Outgoing payment beneficiary name. */
+        name: string;
+        /** Outgoing payment beneficiary type. */
+        type: "agency" | "beneficiary" | "global_beneficiary";
+    };
+    /** Minimal information about the property this payment is associated with. */
+    property: PropertyBasicModel;
+    /** Outgoing payment tax amount. */
+    tax_amount: AmountBase;
+    /** Date the outgoing payment transaction was processed. */
+    transaction_date: DateString;
+}
+/**
+ * Paginated response from `GET /payments/outgoing`.
+ */
+export interface PaymentsOutgoingPagedResult {
+    /** List of outgoing payment items. */
+    items: PaymentsOutgoingModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}
+/**
+ * A single entry in the combined payments view, which may represent an incoming
+ * payment, an outgoing payment, or an invoice.
+ */
+export interface PaymentsCombinedModel {
+    /** Incoming or outgoing payment amount. */
+    amount: AmountBase;
+    /**
+     * Information about file attachments and the relevant payment instruction IDs.
+     *
+     * Only relevant when `payment_type` is `"out"`. Will always be `null` for other types.
+     */
+    attachments: {
+        /** Indicates if the outgoing payment has any attachments assigned to original payment split rules. */
+        has_attachments: boolean;
+        /** List of payment rule IDs that have one or more attachments. */
+        payment_ids: ExternalID[];
+    } | null;
+    /**
+     * Category of the payment entry.
+     *
+     * - For **incoming** payments: ID is always `null`, name is always `"Transfer"`.
+     * - For **outgoing** payments: represents the payment instruction category.
+     * - For **invoices**: represents the invoice category.
+     */
+    category: {
+        /**
+         * PayProp external ID of the category.
+         * For incoming payments this will always be `null`.
+         */
+        id: ExternalID;
+        /**
+         * Category name.
+         * For incoming payments this will always be `"Transfer"`.
+         */
+        name: string;
+    };
+    /**
+     * Date relevant to the payment type.
+     *
+     * - **Incoming** payments: reconciliation date.
+     * - **Outgoing** payments: transaction date.
+     * - **Invoices**: invoice creation date.
+     */
+    date: DateString;
+    /**
+     * Payment description.
+     *
+     * - **Outgoing** payments: the payment instruction description.
+     * - **Invoices**: the invoice description.
+     * - **Incoming** payments: usually `null`. Non-null only when an incoming payment was partially
+     *   split and a description was provided for the split.
+     */
+    description: string | null;
+    /**
+     * Indicates if the invoice or outgoing payment has tax enabled.
+     * Only relevant when `payment_type` is `"out"` or `"invoice"`.
+     */
+    has_tax: boolean;
+    /**
+     * IDs associated with this payment entry.
+     *
+     * - For **invoices** and **incoming** payments: always a single-item list with the reconciled payment ID.
+     * - For **outgoing** payments: the list of grouped outgoing payment record IDs.
+     */
+    ids: ExternalID[];
+    /**
+     * Outgoing batch payment information.
+     * Only relevant when `payment_type` is `"out"`. Will always be `null` for other types.
+     */
+    payment_batch: PaymentBatchModel | null;
+    /**
+     * List of payment origins for this grouped outgoing payment.
+     * Only relevant when `payment_type` is `"out"`. Will always be `null` for other types.
+     */
+    payment_origins: PaymentsOutgoingOriginModel[] | null;
+    /**
+     * The beneficiary who received this outgoing payment.
+     * For invoices and incoming payments this field will always be `null`.
+     */
+    payment_target: {
+        /** PayProp external ID of the beneficiary. */
+        id: ExternalID;
+        /** Outgoing payment beneficiary name. */
+        name: string;
+        /** Outgoing payment beneficiary type. */
+        type: "agency" | "beneficiary" | "global_beneficiary";
+    } | null;
+    /**
+     * Represents the money flow direction of this payment entry.
+     *
+     * - `in` – Incoming monies paid by a tenant or released from other sources (e.g. property account).
+     * - `out` – Outgoing monies paid to a target beneficiary.
+     * - `invoice` – Outgoing ad-hoc invoice instruction.
+     */
+    payment_type: "in" | "out" | "invoice";
+    /** Minimal information about the property this payment is associated with. */
+    property: PropertyBasicModel;
+    /**
+     * Tax amount for the invoice or outgoing payment.
+     * Only relevant when `payment_type` is `"out"` or `"invoice"`.
+     */
+    tax_amount: AmountBase;
+    /**
+     * The tenant associated with this payment.
+     *
+     * - **Incoming** payments: the tenant whose deposit ID was used to reconcile payments.
+     * - **Outgoing** payments: always `null` (funds can come from multiple sources).
+     * - **Invoices**: the tenant for whom the invoice was raised.
+     */
+    tenant: TenantBasicModel | null;
+    /**
+     * Incoming payment transaction type.
+     *
+     * Only relevant when `payment_type` is `"in"` or `"invoice"`.
+     * Will always be `null` for outgoing payments.
+     *
+     * - `invoice` – Invoice entry
+     * - `payment` – Standard incoming payment
+     * - `payment_prop_acc` – Transfer from property account
+     * - `deposit_repayment` – Release from deposit account
+     * - `unknown` – Unmapped transaction type
+     */
+    transaction_type: "invoice" | "payment" | "payment_prop_acc" | "deposit_repayment" | "unknown" | null;
+}
+/**
+ * Paginated response from `GET /payments/combined`.
+ */
+export interface PaymentsCombinedPagedResult {
+    /** List of combined payment items (incoming, outgoing, and invoices). */
+    items: PaymentsCombinedModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}
+/**
+ * Summary of money flow for a given date range.
+ * Returned from `GET /payments/summary`.
+ */
+export interface PaymentsSummaryModel {
+    /**
+     * Total ad-hoc and recurring invoice amounts for the given date range.
+     * Includes both outstanding and paid invoice amounts.
+     */
+    invoiced: AmountBase | null;
+    /** Total money received from tenants. */
+    money_in: AmountBase | null;
+    /** Total money paid out to beneficiaries. */
+    money_out: AmountBase | null;
+    /** Total payments made to the current owner entity. */
+    paid_to_owner: AmountBase | null;
+    /** Information about property balances. */
+    properties: {
+        /** Property opening and closing balances for the given date range. */
+        balances: {
+            /**
+             * Closing balance: sum of all transactions up to and including `to_date`
+             * where outgoing payments have not yet been paid out.
+             */
+            closing: AmountBase;
+            /**
+             * Opening balance: sum of all transactions before `from_date`
+             * where outgoing payments have not yet been paid out.
+             */
+            opening: AmountBase;
+        };
+    };
+    /** Information about property account funds. */
+    property_accounts: {
+        /** Property account opening and closing balances for the given date range. */
+        balances: {
+            /** Sum of all incoming and outgoing property account payments up to `to_date` inclusive. */
+            closing: AmountBase;
+            /** Sum of all incoming and outgoing property account payments before the report `from_date`. */
+            opening: AmountBase;
+        };
+    };
+    /** Total outstanding arrears amount across all tenants. */
+    tenants_in_arrears: AmountBase | null;
+}

package/dist/types/payment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/properties.d.ts

@@ -0,0 +1,35 @@
+import type { AddressModel, AgencyBasicModel, BeneficiaryBasicModel, ExternalID, PaginationModel } from "./shared";
+/**
+ * Full property entity. Contains all property details including address,
+ * agency association, and optional beneficiary list.
+ */
+export interface PropertyModel {
+    /** Address of the property. */
+    address?: AddressModel;
+    /** Minimal information about the agency managing this property. */
+    agency?: AgencyBasicModel;
+    /**
+     * List of beneficiaries that have an ownership of the property for the specified ownership range.
+     * Only present when the `with_beneficiaries` query parameter is set to `true`.
+     */
+    beneficiaries?: BeneficiaryBasicModel[] | null;
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** URL of the property image, or null if no image has been set. */
+    image?: string | null;
+    /** Indicates if the property is active on PayProp. */
+    is_active: boolean;
+    /** Property name. */
+    name: string;
+    /** Number of unique tenants that have an active tenancy on the property. */
+    number_of_tenants?: number;
+}
+/**
+ * Paginated response from `GET /properties`.
+ */
+export interface PropertiesPagedResult {
+    /** List of property entities. */
+    items: PropertyModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}

package/dist/types/properties.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/shared.d.ts

@@ -0,0 +1,115 @@
+/**
+ * PayProp external ID.
+ * Alphanumeric string between 10 and 32 characters.
+ * @example 'zJBv2E5aJQ'
+ */
+export type ExternalID = string;
+/**
+ * Monetary amount. Decimal number with up to 2 decimal places.
+ * @example 9650.12
+ */
+export type AmountBase = number;
+/**
+ * Nullable monetary amount. Decimal number with up to 2 decimal places, or null.
+ * @example 9650.12
+ */
+export type AmountNullable = number | null;
+/**
+ * ISO date string in the format YYYY-MM-DD.
+ * @example '2025-10-21'
+ */
+export type DateString = string;
+/**
+ * Nullable ISO date string in the format YYYY-MM-DD, or null.
+ * @example '2025-10-21'
+ */
+export type DateStringNullable = string | null;
+/**
+ * Pagination metadata returned on all paginated endpoints.
+ */
+export interface PaginationModel {
+    /** Current page number. */
+    page: number;
+    /** Total number of items on the current page. */
+    rows: number;
+    /** Total number of pages. */
+    total_pages: number;
+    /** Total number of items found across all pages. */
+    total_rows: number;
+}
+/**
+ * Entity address information.
+ *
+ * In rare cases the address field can be `null` for historical entities
+ * where the information was not collected on the system.
+ */
+export type AddressModel = {
+    /** City. */
+    city: string;
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Address line 1. */
+    line_1: string;
+    /** Address line 2. */
+    line_2: string;
+    /** Address line 3. */
+    line_3: string;
+    /** Postal code. */
+    postal_code: string;
+    /** State. */
+    state: string;
+} | null;
+/**
+ * Minimal info about the agency.
+ * For full agency data call `/agencies`.
+ */
+export interface AgencyBasicModel {
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Indicates if the agency is active on PayProp. */
+    is_active: boolean;
+    /** Agency name. */
+    name: string;
+}
+/**
+ * Minimal info about the beneficiary.
+ * For full beneficiary data call `/beneficiaries`.
+ */
+export interface BeneficiaryBasicModel {
+    /** Business name. */
+    business_name: string;
+    /** Formatted beneficiary display name used on platform. */
+    display_name: string;
+    /** Beneficiary first name. */
+    first_name: string;
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Beneficiary last name. */
+    last_name: string;
+}
+/**
+ * Minimal info about the property.
+ * For full property data call `/properties`.
+ */
+export interface PropertyBasicModel {
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Property name. */
+    name: string;
+}
+/**
+ * Minimal info about the tenant.
+ * For full tenant data call `/tenants`.
+ */
+export interface TenantBasicModel {
+    /** Business name. */
+    business_name: string;
+    /** Formatted tenant display name used on platform. */
+    display_name: string;
+    /** Tenant first name. */
+    first_name: string;
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Tenant last name. */
+    last_name: string;
+}

package/dist/types/shared.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/tenant.d.ts

@@ -0,0 +1,132 @@
+import type { AgencyBasicModel, AmountBase, DateString, DateStringNullable, ExternalID, PaginationModel, PropertyBasicModel, TenantBasicModel } from "./shared";
+/**
+ * Full tenant entity with all tenant details.
+ */
+export interface TenantModel {
+    /** Minimal information about the agency associated with this tenant. */
+    agency: AgencyBasicModel;
+    /** Business name. */
+    business_name: string;
+    /** Formatted tenant display name used on the platform. */
+    display_name: string;
+    /** Tenant first name. */
+    first_name: string;
+    /**
+     * Indicates if the current tenant has one or more active tenancies
+     * across all properties, or filtered by `property_id` if provided.
+     */
+    has_active_tenancy: boolean;
+    /** PayProp external ID. */
+    id: ExternalID;
+    /** Indicates if the tenant is active on PayProp. */
+    is_active: boolean;
+    /** Tenant last name. */
+    last_name: string;
+}
+/**
+ * Paginated response from `GET /tenants`.
+ */
+export interface TenantsPagedResult {
+    /** List of tenant entities. */
+    items: TenantModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}
+/**
+ * Tenant balance item showing opening and closing balances for a given date range.
+ */
+export interface TenantsBalancesModel {
+    /** Minimal information about the agency associated with this tenant. */
+    agency: AgencyBasicModel;
+    /** Opening and closing balances for the requested date range. */
+    balance: {
+        /**
+         * Closing balance: sum of all transactions up to and including `closing_balance_date`.
+         *
+         * A negative value means the tenant is in arrears.
+         * A positive value means the tenant is in credit.
+         */
+        closing: AmountBase;
+        /**
+         * Opening balance: sum of all transactions before `opening_balance_date`.
+         *
+         * A negative value means the tenant is in arrears.
+         * A positive value means the tenant is in credit.
+         */
+        opening: AmountBase;
+    };
+    /** Minimal information about the property associated with this tenant balance. */
+    property: PropertyBasicModel;
+    /** Minimal information about the tenant. */
+    tenant: TenantBasicModel;
+}
+/**
+ * Paginated response from `GET /tenants/balances`.
+ */
+export interface TenantsBalancesPagedResult {
+    /** List of tenant balance items. */
+    items: TenantsBalancesModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}
+/**
+ * A tenancy record representing a tenant's occupancy period on a property.
+ *
+ * Multiple tenancy records may exist for the same tenant and property combination,
+ * calculated based on rental invoices with varying periods.
+ * Records are ordered by `start_date` descending (most recent first).
+ */
+export interface TenantsTenanciesModel {
+    /** Minimal information about the agency managing the property. */
+    agency: AgencyBasicModel;
+    /**
+     * Tenancy end date.
+     * `null` if the tenancy has no defined end date (open-ended).
+     */
+    end_date: DateStringNullable;
+    /** PayProp external ID of this tenancy record. */
+    id: ExternalID;
+    /** Indicates if the current tenancy period is active. */
+    is_active: boolean;
+    /** Minimal information about the property associated with this tenancy. */
+    property: PropertyBasicModel;
+    /**
+     * Estimated rent information for this tenancy period.
+     *
+     * **Important:** This field may be inaccurate or absent. It is derived from recurring rent invoices
+     * matched to the tenancy period, which is not always possible to do accurately.
+     * Use this field as a general indication only and not as a source of truth.
+     */
+    rent: {
+        /** Rent invoice amount. */
+        amount: AmountBase;
+        /**
+         * Frequency at which the rent invoice is generated.
+         *
+         * - `A` – Annual
+         * - `Q` – Quarterly
+         * - `M` – Monthly
+         * - `W` – Weekly
+         * - `2M` – Every two months
+         * - `2W` – Every two weeks
+         * - `4W` – Every four weeks
+         * - `6M` – Every six months
+         */
+        frequency: "A" | "Q" | "M" | "W" | "2M" | "2W" | "4W" | "6M";
+        /** PayProp external ID of the associated rent invoice rule. */
+        id: ExternalID;
+    } | null;
+    /** Tenancy start date. */
+    start_date: DateString;
+    /** Minimal information about the tenant occupying the property. */
+    tenant: TenantBasicModel;
+}
+/**
+ * Paginated response from `GET /tenants/tenancies`.
+ */
+export interface TenantsTenanciesPagedResult {
+    /** List of tenancy records. */
+    items: TenantsTenanciesModel[];
+    /** Pagination metadata. */
+    pagination: PaginationModel;
+}

package/dist/types/tenant.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/user.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Address associated with a user.
+ */
+export interface UserAddressModel {
+    /** Address line 1. */
+    line_1: string;
+    /** Address line 2. */
+    line_2: string;
+    /** Address line 3. */
+    line_3: string;
+    /** City. */
+    city: string;
+    /** Postal code. */
+    postal_code: string;
+}
+/**
+ * Tenant-specific metadata as returned in API responses.
+ */
+export interface TenantMetadataModel {
+    /** Tenant first name. */
+    first_name?: string;
+    /** Tenant last name. */
+    last_name?: string;
+}
+/**
+ * Partial tenant metadata for write operations (`PUT /private/users`, `PUT /public/metadata`).
+ * All fields are optional — only the fields provided will be updated.
+ */
+export type TenantMetadataPayloadModel = Partial<TenantMetadataModel>;
+/**
+ * Owner-specific metadata as returned in API responses.
+ */
+export interface OwnerMetadataModel {
+    /** Owner first name. */
+    first_name: string;
+    /** Owner last name. */
+    last_name: string;
+    /** Business name. */
+    business_name: string;
+    /** Tax code. */
+    tax_code: string;
+    /** Indicates whether the owner has reviewed their information. */
+    is_info_reviewed: boolean;
+    /** Owner address. */
+    address: UserAddressModel;
+    /** Annual statement generation schedule. */
+    annual_statement: {
+        /**
+         * Day of the month for the annual statement.
+         * Must be between 1 and 31.
+         */
+        day: number;
+        /**
+         * Month of the year for the annual statement.
+         * Must be between 1 and 12.
+         */
+        month: number;
+    };
+}
+/**
+ * Partial owner metadata for write operations (`PUT /private/users`, `PUT /public/metadata`).
+ * All fields are optional — only the fields provided will be updated.
+ */
+export type OwnerMetadataPayloadModel = Partial<OwnerMetadataModel>;
+/**
+ * Metadata as returned by `GET /public/metadata` and in user responses.
+ * Either `owner`, `tenant`, or both may be present depending on the user's role(s).
+ */
+export interface PublicMetadataModel {
+    /** Owner metadata. Only present when the user has the `owner` role. */
+    owner: OwnerMetadataModel;
+    /** Tenant metadata. Only present when the user has the `tenant` role. */
+    tenant: TenantMetadataModel;
+}
+/**
+ * Partial metadata payload for write operations (`PUT /public/metadata`, `PUT /private/users`).
+ * Pass `owner`, `tenant`, or both — only the provided fields will be updated.
+ */
+export interface PublicMetadataPayloadModel {
+    /** Partial owner metadata to update. */
+    owner?: OwnerMetadataPayloadModel;
+    /** Partial tenant metadata to update. */
+    tenant?: TenantMetadataPayloadModel;
+}
+/**
+ * User role.
+ *
+ * - `owner` – Property owner
+ * - `tenant` – Tenant
+ */
+export type UserRoleModel = "owner" | "tenant";
+/**
+ * An individual Cognito user attribute name/value pair.
+ */
+export interface UserCognitoAttributeModel {
+    /** Attribute name (e.g. `email`, `sub`). */
+    Name: string;
+    /** Attribute value. */
+    Value: string;
+}
+/**
+ * Cognito user object as returned by `AdminCreateUserCommand`.
+ * See [AWS Cognito UserType docs](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UserType.html) for details.
+ */
+export interface UserCognitoModel {
+    /** Cognito username (usually the `sub`). */
+    Username: string;
+    /** Whether the user account is enabled. */
+    Enabled: boolean;
+    /** ISO date-time string of when the user was created. */
+    UserCreateDate: string;
+    /** ISO date-time string of when the user was last modified. */
+    UserLastModifiedDate: string;
+    /**
+     * Cognito account status.
+     *
+     * - `UNCONFIRMED` – User has been created but not confirmed
+     * - `CONFIRMED` – User has been confirmed
+     * - `ARCHIVED` – User is no longer active
+     * - `COMPROMISED` – User is disabled due to a potential security threat
+     * - `UNKNOWN` – Status cannot be determined
+     * - `RESET_REQUIRED` – User must reset their password at next sign-in
+     * - `FORCE_CHANGE_PASSWORD` – User must change their password at next sign-in
+     */
+    UserStatus: "UNCONFIRMED" | "CONFIRMED" | "ARCHIVED" | "COMPROMISED" | "UNKNOWN" | "RESET_REQUIRED" | "FORCE_CHANGE_PASSWORD";
+    /** List of user attributes as name/value pairs. */
+    Attributes: UserCognitoAttributeModel[];
+}
+/**
+ * Response returned from `GET /private/users`, `PUT /private/users`,
+ * `POST /private/users`, and `PUT /public/metadata`.
+ *
+ * Contains the Cognito user object and optional metadata.
+ */
+export interface UserModel {
+    /** Cognito user object. */
+    User: UserCognitoModel;
+    /** User metadata payload containing owner and/or tenant metadata. */
+    metadata?: PublicMetadataModel;
+}
+/**
+ * Request body for `PUT /private/users`.
+ * Updates user metadata using the specified merge strategy.
+ */
+export interface UserUpdateRequestModel {
+    /** Metadata to apply to the user. Pass `owner`, `tenant`, or both. */
+    metadata?: PublicMetadataModel;
+}
+/**
+ * A single entry in the owner invitation request.
+ * Must include either `id` or `email`.
+ */
+export interface SendOwnerInvitationItemModel {
+    /** User ID (alternative to `email`). */
+    id: string;
+    /** User email address (alternative to `id`). */
+    email?: string;
+}
+/**
+ * Request body for `POST /private/send-owner-invitation`.
+ * Array of 1–50 owner invitation entries, each requiring either an `id` or `email`.
+ */
+export type SendOwnerInvitationRequestModel = SendOwnerInvitationItemModel[];
+/**
+ * Response from `POST /private/send-owner-invitation`.
+ */
+export interface SendOwnerInvitationModel {
+    /** Invitation enqueue result. */
+    invitations: {
+        /** Number of invitations received. */
+        received?: number;
+        /** Number of invitations successfully enqueued. */
+        enqueued?: number;
+    };
+}
+/**
+ * Request body for `POST /private/users` when creating an owner.
+ */
+export interface UserCreateOwnerRequestModel {
+    /** User email address. */
+    email: string;
+    /** Must be `"owner"`. */
+    role: "owner";
+    /** Owner metadata to set on creation. All fields are optional. */
+    metadata?: OwnerMetadataPayloadModel;
+}
+/**
+ * Request body for `POST /private/users` when creating a tenant.
+ */
+export interface UserCreateTenantRequestModel {
+    /** User email address. */
+    email: string;
+    /** Must be `"tenant"`. */
+    role: "tenant";
+    /** Tenant metadata to set on creation. All fields are optional. */
+    metadata?: TenantMetadataPayloadModel;
+}
+/**
+ * Request body for `POST /private/users`.
+ * Use `UserCreateOwnerRequestModel` or `UserCreateTenantRequestModel` depending on the role.
+ */
+export type UserCreateRequestModel = UserCreateOwnerRequestModel | UserCreateTenantRequestModel;

package/dist/types/user.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@reapit/gbl-pp-owner-api-ts-definitions",
+  "version": "1.0.0",
+  "description": "TypeScript type definitions for the PayProp Owner API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "prepublishOnly": "yarn build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.2",
+    "@types/react": "^19.2.14",
+    "typescript": "^5.6.2"
+  },
+  "packageManager": "yarn@4.13.0+sha512.5c20ba010c99815433e5c8453112165e673f1c7948d8d2b267f4b5e52097538658388ebc9f9580656d9b75c5cc996f990f611f99304a2197d4c56d21eea370e7"
+}