xero-kiwi 0.1.0

data/docs/accounting/credit-note.md

@@ -0,0 +1,97 @@
+# Credit Notes
+
+A Xero **credit note** is a document that reduces the amount owed on an
+invoice. Credit notes can be applied (allocated) to outstanding invoices. You
+need a `tenant_id` from a [connection](../connections.md) before you can fetch
+credit notes.
+
+> See: [Xero docs — Credit Notes](https://developer.xero.com/documentation/api/accounting/creditnotes)
+
+## Listing credit notes
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+credit_notes = client.credit_notes("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+credit_notes = client.credit_notes(connection)
+```
+
+`client.credit_notes` hits `GET /api.xro/2.0/CreditNotes` with the
+`Xero-Tenant-Id` header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::CreditNote>`.
+
+## Fetching a single credit note
+
+```ruby
+cn = client.credit_note(tenant_id, "aea95d78-ea48-456b-9b08-6bc012600072")
+cn.total  # => 100.00
+```
+
+`client.credit_note` hits `GET /api.xro/2.0/CreditNotes/{CreditNoteID}` and
+returns a single `XeroKiwi::Accounting::CreditNote`, or `nil` if the response is
+empty. The single-credit-note response includes full line item details.
+
+## The CreditNote object
+
+Each `XeroKiwi::Accounting::CreditNote` is an immutable value object exposing the
+fields Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `credit_note_id` | `String` | The unique Xero identifier. |
+| `credit_note_number` | `String` | The credit note number (e.g. `"CN-0002"`). |
+| `type` | `String` | `"ACCRECCREDIT"` (accounts receivable) or `"ACCPAYCREDIT"` (accounts payable). |
+| `contact` | `XeroKiwi::Accounting::Contact` | The contact (reference — use `contact.reference?` to check). See [Contacts](contact.md). |
+| `date` | `Time` | The date the credit note was issued, parsed as UTC. |
+| `status` | `String` | e.g. `"DRAFT"`, `"SUBMITTED"`, `"AUTHORISED"`, `"PAID"`, `"VOIDED"`. |
+| `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
+| `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items. See [Prepayments — LineItem](prepayment.md#the-lineitem-object). |
+| `sub_total` | `Numeric` | The subtotal excluding taxes. |
+| `total_tax` | `Numeric` | The total tax amount. |
+| `total` | `Numeric` | The total (subtotal + total tax). |
+| `cis_deduction` | `Numeric` | CIS deduction (UK Construction Industry Scheme only). |
+| `updated_date_utc` | `Time` | When the credit note was last modified, parsed as UTC. |
+| `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
+| `currency_rate` | `Numeric` | The currency rate (1.0 for base currency). |
+| `fully_paid_on_date` | `Time` | When the credit note was fully allocated, parsed as UTC. |
+| `reference` | `String` | Additional reference number (ACCRECCREDIT only). |
+| `sent_to_contact` | `Boolean` | Whether the credit note has been sent to the contact. |
+| `remaining_credit` | `Numeric` | The remaining credit balance. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `branding_theme_id` | `String` | The branding theme ID applied to the credit note. |
+| `has_attachments` | `Boolean` | Whether the credit note has attachments. |
+
+## Predicates
+
+```ruby
+cn.accounts_receivable?  # type == "ACCRECCREDIT"
+cn.accounts_payable?     # type == "ACCPAYCREDIT"
+```
+
+## Equality and hashing
+
+Two credit notes are `==` if they share the same `credit_note_id`. `#hash` is
+consistent with `==`, so credit notes work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns credit notes) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The credit note ID doesn't exist |
+
+## Common patterns
+
+### Listing credit notes with remaining credit
+
+```ruby
+credit_notes = client.credit_notes(tenant_id)
+with_credit = credit_notes.select { |cn| cn.remaining_credit.to_f > 0 }
+with_credit.each { |cn| puts "#{cn.credit_note_number}: #{cn.remaining_credit} remaining" }
+```

data/docs/accounting/external-link.md

@@ -0,0 +1,33 @@
+# XeroKiwi::Accounting::ExternalLink
+
+A Xero external link (social or web profile). Used by
+[Organisation](organisation.md).
+
+> See: [Xero docs — External link types](https://developer.xero.com/documentation/api/accounting/types#externallinks)
+
+## Usage
+
+```ruby
+org.external_links.each do |link|
+  puts "#{link.link_type}: #{link.url}"
+end
+```
+
+## Attributes
+
+| Attribute | Type | Notes |
+|-----------|------|-------|
+| `link_type` | `String` | `"Facebook"`, `"GooglePlus"`, `"LinkedIn"`, `"Twitter"`, or `"Website"` |
+| `url` | `String` | The URL for the service |
+
+## Equality
+
+Two external links are `==` if all their attributes match. `#hash` is
+consistent with `==`.
+
+## Serialisation
+
+```ruby
+link.to_h
+# => { link_type: "Facebook", url: "https://facebook.com/example" }
+```

data/docs/accounting/invoice.md

@@ -0,0 +1,134 @@
+# Invoices
+
+A Xero **invoice** is either a sales invoice (accounts receivable, `ACCREC`) or
+a purchase bill (accounts payable, `ACCPAY`). Invoices carry line items,
+payments, credit notes, and allocation details. You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch invoices.
+
+> See: [Xero docs — Invoices](https://developer.xero.com/documentation/api/accounting/invoices)
+
+## Listing invoices
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+invoices = client.invoices("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+invoices = client.invoices(connection)
+```
+
+`client.invoices` hits `GET /api.xro/2.0/Invoices` with the `Xero-Tenant-Id`
+header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::Invoice>`.
+
+**Note:** The list response returns only a summary of each contact and no line
+items. Fetch an individual invoice for full details including line items.
+
+## Fetching a single invoice
+
+```ruby
+inv = client.invoice(tenant_id, "243216c5-369e-4056-ac67-05388f86dc81")
+inv.total           # => "2025.00"
+inv.invoice_number  # => "OIT00546"
+```
+
+`client.invoice` hits `GET /api.xro/2.0/Invoices/{InvoiceID}` and returns a
+single `XeroKiwi::Accounting::Invoice`, or `nil` if the response is empty.
+
+## The Invoice object
+
+Each `XeroKiwi::Accounting::Invoice` is an immutable value object. The fields below
+cover both the list and single-invoice responses:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `invoice_id` | `String` | The unique Xero identifier. |
+| `invoice_number` | `String` | The invoice number (e.g. `"OIT00546"`). |
+| `type` | `String` | `"ACCREC"` (sales) or `"ACCPAY"` (bills). |
+| `contact` | `XeroKiwi::Accounting::Contact` | The contact (reference — use `contact.reference?` to check). See [Contacts](contact.md). |
+| `date` | `Time` | The invoice date, parsed as UTC. |
+| `due_date` | `Time` | The due date, parsed as UTC. |
+| `status` | `String` | e.g. `"DRAFT"`, `"SUBMITTED"`, `"AUTHORISED"`, `"PAID"`, `"VOIDED"`, `"DELETED"`. |
+| `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
+| `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items (empty on list, populated on single). See [Prepayments — LineItem](prepayment.md#the-lineitem-object). |
+| `sub_total` | `String/Numeric` | The subtotal excluding taxes. |
+| `total_tax` | `String/Numeric` | The total tax amount. |
+| `total` | `String/Numeric` | The total (subtotal + total tax). |
+| `total_discount` | `String/Numeric` | Total discounts on line items. |
+| `updated_date_utc` | `Time` | When the invoice was last modified, parsed as UTC. |
+| `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
+| `currency_rate` | `Numeric` | The currency rate (1.0 for base currency). |
+| `reference` | `String` | Additional reference number (ACCREC only). |
+| `branding_theme_id` | `String` | The branding theme ID. |
+| `url` | `String` | URL link to a source document. |
+| `sent_to_contact` | `Boolean` | Whether the invoice displays as "sent" in Xero. |
+| `expected_payment_date` | `Time` | Expected payment date (ACCREC only). |
+| `planned_payment_date` | `Time` | Planned payment date (ACCPAY only). |
+| `has_attachments` | `Boolean` | Whether the invoice has attachments. |
+| `repeating_invoice_id` | `String` | The repeating invoice template ID, if applicable. |
+| `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
+| `credit_notes` | `Array<Hash>` | Credit notes applied (raw hashes). |
+| `prepayments` | `Array<Hash>` | Prepayments applied (raw hashes). |
+| `overpayments` | `Array<Hash>` | Overpayments applied (raw hashes). |
+| `amount_due` | `String/Numeric` | Amount remaining to be paid. |
+| `amount_paid` | `String/Numeric` | Sum of payments received. |
+| `amount_credited` | `String/Numeric` | Sum of credit notes, overpayments, and prepayments applied. |
+| `cis_deduction` | `Numeric` | CIS deduction (UK Construction Industry Scheme only). |
+| `fully_paid_on_date` | `Time` | When the invoice was fully paid, parsed as UTC. |
+| `sales_tax_calculation_type_code` | `String` | US auto sales tax calculation type. |
+| `invoice_addresses` | `Array<Hash>` | Invoice addresses (US auto sales tax only). |
+
+## Predicates
+
+```ruby
+inv.accounts_receivable?  # type == "ACCREC"
+inv.accounts_payable?     # type == "ACCPAY"
+```
+
+## Equality and hashing
+
+Two invoices are `==` if they share the same `invoice_id`. `#hash` is consistent
+with `==`, so invoices work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns invoices) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The invoice ID doesn't exist |
+
+## Common patterns
+
+### Retrieving the online invoice URL
+
+For sales (ACCREC) invoices that are not in DRAFT status, you can retrieve the
+online invoice URL that customers can use to view and pay:
+
+```ruby
+url = client.online_invoice_url(tenant_id, "243216c5-369e-4056-ac67-05388f86dc81")
+puts url  # => "https://in.xero.com/iztKMjyAEJT7MVnmruxgCdIJUDStfRgmtdQSIW13"
+```
+
+Returns `nil` if no online invoice URL is available.
+
+### Listing outstanding invoices
+
+```ruby
+invoices = client.invoices(tenant_id)
+outstanding = invoices.select { |inv| inv.amount_due.to_f > 0 }
+outstanding.each { |inv| puts "#{inv.invoice_number}: #{inv.amount_due} due" }
+```
+
+### Fetching an invoice with full line items
+
+```ruby
+inv = client.invoice(tenant_id, "243216c5-369e-4056-ac67-05388f86dc81")
+inv.line_items.each do |li|
+  puts "  #{li.description}: #{li.line_amount}"
+end
+```

data/docs/accounting/organisation.md

@@ -0,0 +1,119 @@
+# Organisation
+
+A Xero **organisation** is the actual accounting entity — the company, sole
+trader, trust, etc. that owns the books. You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch one.
+
+> See: [Xero docs — Organisation](https://developer.xero.com/documentation/api/accounting/organisation)
+
+## Fetching an organisation
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+org = client.organisation("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+org = client.organisation(connection)
+```
+
+`client.organisation` hits `GET /api.xro/2.0/Organisation` with the
+`Xero-Tenant-Id` header set to the tenant you specify. It returns a single
+`XeroKiwi::Accounting::Organisation`.
+
+## The Organisation object
+
+Each `XeroKiwi::Accounting::Organisation` is an immutable value object exposing the fields
+Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `organisation_id` | `String` | The unique identifier for the organisation. |
+| `api_key` | `String` | The API key (if set). |
+| `name` | `String` | The display name (e.g. "Maple Florists Ltd"). |
+| `legal_name` | `String` | The registered legal name. |
+| `pays_tax` | `Boolean` | Whether the organisation is registered for tax. |
+| `version` | `String` | The Xero edition version code (e.g. `"NZ"`, `"GLOBAL"`). |
+| `organisation_type` | `String` | The type — `"COMPANY"`, `"SOLE_TRADER"`, `"TRUST"`, etc. |
+| `base_currency` | `String` | The base currency code (e.g. `"NZD"`, `"ZAR"`). |
+| `country_code` | `String` | The two-letter country code (e.g. `"NZ"`, `"ZA"`). |
+| `is_demo_company` | `Boolean` | Whether this is a Xero demo company. |
+| `organisation_status` | `String` | `"ACTIVE"` or otherwise. |
+| `registration_number` | `String` | The company registration number. |
+| `employer_identification_number` | `String` | The EIN (US organisations). |
+| `tax_number` | `String` | The tax/VAT number. |
+| `financial_year_end_day` | `Integer` | Day of month the financial year ends (1–31). |
+| `financial_year_end_month` | `Integer` | Month the financial year ends (1–12). |
+| `sales_tax_basis` | `String` | e.g. `"Payments"`, `"CASH"`, `"ACCRUALS"`. |
+| `sales_tax_period` | `String` | e.g. `"TWOMONTHS"`, `"MONTHLY"`. |
+| `default_sales_tax` | `String` | e.g. `"Tax Exclusive"`. |
+| `default_purchases_tax` | `String` | e.g. `"Tax Exclusive"`. |
+| `period_lock_date` | `Time` | The period lock date, parsed as UTC. |
+| `end_of_year_lock_date` | `Time` | The end-of-year lock date, parsed as UTC. |
+| `created_date_utc` | `Time` | When the organisation was created, parsed as UTC. |
+| `timezone` | `String` | The organisation's timezone code (e.g. `"NEWZEALANDSTANDARDTIME"`). |
+| `organisation_entity_type` | `String` | The entity type (e.g. `"COMPANY"`). |
+| `short_code` | `String` | The Xero short code for this organisation. |
+| `organisation_class` | `String` | The Xero subscription class (e.g. `"PREMIUM"`, `"STARTER"`). |
+| `edition` | `String` | The Xero subscription edition (e.g. `"BUSINESS"`). |
+| `line_of_business` | `String` | The industry / line of business. |
+| `addresses` | `Array<XeroKiwi::Accounting::Address>` | The organisation's addresses. See [Address](address.md). |
+| `phones` | `Array<XeroKiwi::Accounting::Phone>` | The organisation's phone numbers. See [Phone](phone.md). |
+| `external_links` | `Array<XeroKiwi::Accounting::ExternalLink>` | Social/web profile links. See [ExternalLink](external-link.md). |
+| `payment_terms` | `XeroKiwi::Accounting::PaymentTerms` | Default payment terms for bills and sales. See [PaymentTerms](payment-terms.md). |
+
+## Predicates
+
+```ruby
+org.demo_company? # is_demo_company == true
+```
+
+## Equality and hashing
+
+Two organisations are `==` if they share the same `organisation_id`. `#hash`
+is consistent with `==`, so organisations work as hash keys and in sets.
+
+## Date parsing
+
+The Xero Accounting API serialises timestamps differently from the Connections
+API. Connections use ISO 8601 strings (e.g. `"2019-07-09T23:40:30.1833130"`),
+but the Accounting API (including Organisation) uses the legacy .NET JSON
+format: `/Date(1574275974000)/`.
+
+XeroKiwi handles both transparently — all `Time` attributes are parsed to UTC
+`Time` objects regardless of which format Xero sends. You don't need to think
+about this unless you're looking at raw cassette data or debugging timestamp
+issues.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns the organisation) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the `accounting.settings.read` scope |
+| 404 | `XeroKiwi::ClientError` | The tenant ID doesn't correspond to an organisation |
+
+## Common patterns
+
+### From connection to organisation
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+client.connections.each do |conn|
+  org = client.organisation(conn)
+  puts "#{org.name} (#{org.base_currency}) — #{org.country_code}"
+end
+```
+
+### Checking if it's a demo company
+
+```ruby
+org = client.organisation(tenant_id)
+if org.demo_company?
+  puts "This is a demo company — data isn't real"
+end
+```

data/docs/accounting/overpayment.md

@@ -0,0 +1,94 @@
+# Overpayments
+
+A Xero **overpayment** is an excess payment received or made beyond the amount
+of an invoice. Overpayments are created via the BankTransactions endpoint and
+refunded via the Payments endpoint. This resource lets you retrieve overpayments
+and their allocations. You need a `tenant_id` from a
+[connection](../connections.md) before you can fetch overpayments.
+
+> See: [Xero docs — Overpayments](https://developer.xero.com/documentation/api/accounting/overpayments)
+
+## Listing overpayments
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+overpayments = client.overpayments("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+overpayments = client.overpayments(connection)
+```
+
+`client.overpayments` hits `GET /api.xro/2.0/Overpayments` with the
+`Xero-Tenant-Id` header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::Overpayment>`.
+
+## Fetching a single overpayment
+
+```ruby
+op = client.overpayment(tenant_id, "aea95d78-ea48-456b-9b08-6bc012600072")
+op.total  # => "100.00"
+```
+
+`client.overpayment` hits `GET /api.xro/2.0/Overpayments/{OverpaymentID}` and
+returns a single `XeroKiwi::Accounting::Overpayment`, or `nil` if the response is
+empty.
+
+## The Overpayment object
+
+Each `XeroKiwi::Accounting::Overpayment` is an immutable value object exposing the
+fields Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `overpayment_id` | `String` | The unique Xero identifier. |
+| `type` | `String` | `"RECEIVE-OVERPAYMENT"` or `"SPEND-OVERPAYMENT"`. |
+| `contact` | `XeroKiwi::Accounting::Contact` | The contact (reference — use `contact.reference?` to check). See [Contacts](contact.md). |
+| `date` | `Time` | The date the overpayment was made, parsed as UTC. |
+| `status` | `String` | e.g. `"AUTHORISED"`, `"PAID"`, `"VOIDED"`. |
+| `line_amount_types` | `String` | `"Inclusive"`, `"Exclusive"`, or `"NoTax"`. |
+| `line_items` | `Array<XeroKiwi::Accounting::LineItem>` | The line items. See [Prepayments — LineItem](prepayment.md#the-lineitem-object). |
+| `sub_total` | `String` | The subtotal excluding taxes. |
+| `total_tax` | `String` | The total tax amount. |
+| `total` | `String` | The total (subtotal + total tax). |
+| `updated_date_utc` | `Time` | When the overpayment was last modified, parsed as UTC. |
+| `currency_code` | `String` | The currency code (e.g. `"NZD"`). |
+| `currency_rate` | `String` | The currency rate (1.0 for base currency). |
+| `remaining_credit` | `String` | The remaining credit balance. |
+| `allocations` | `Array<XeroKiwi::Accounting::Allocation>` | Allocations to invoices. Each allocation has an `invoice` reference. |
+| `payments` | `Array<XeroKiwi::Accounting::Payment>` | Payment records (references). See [Payments](payment.md). |
+| `has_attachments` | `Boolean` | Whether the overpayment has attachments. |
+| `reference` | `String` | Reference for the overpayment. |
+
+## Predicates
+
+```ruby
+op.receive?  # type == "RECEIVE-OVERPAYMENT"
+op.spend?    # type == "SPEND-OVERPAYMENT"
+```
+
+## Equality and hashing
+
+Two overpayments are `==` if they share the same `overpayment_id`. `#hash` is
+consistent with `==`, so overpayments work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns overpayments) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The overpayment ID doesn't exist |
+
+## Common patterns
+
+### Listing overpayments with remaining credit
+
+```ruby
+overpayments = client.overpayments(tenant_id)
+with_credit = overpayments.select { |op| op.remaining_credit.to_f > 0 }
+with_credit.each { |op| puts "#{op.overpayment_id}: #{op.remaining_credit} remaining" }
+```

data/docs/accounting/payment-terms.md

@@ -0,0 +1,58 @@
+# XeroKiwi::Accounting::PaymentTerms
+
+Default payment terms for an organisation or contact, containing separate
+terms for bills (accounts payable) and sales invoices (accounts receivable).
+
+> See: [Xero docs — Payment terms](https://developer.xero.com/documentation/api/accounting/types#paymentterms)
+
+## Usage
+
+```ruby
+if org.payment_terms
+  bills = org.payment_terms.bills
+  sales = org.payment_terms.sales
+
+  puts "Bills due: day #{bills.day} (#{bills.type})" if bills
+  puts "Sales due: day #{sales.day} (#{sales.type})" if sales
+end
+```
+
+## PaymentTerms attributes
+
+| Attribute | Type | Notes |
+|-----------|------|-------|
+| `bills` | `XeroKiwi::Accounting::PaymentTerm` | Default terms for accounts payable. `nil` if not configured. |
+| `sales` | `XeroKiwi::Accounting::PaymentTerm` | Default terms for accounts receivable. `nil` if not configured. |
+
+`PaymentTerms` itself is `nil` on the parent object when the organisation or
+contact has no payment terms configured at all.
+
+## PaymentTerm attributes
+
+Each side (bills or sales) is a `XeroKiwi::Accounting::PaymentTerm`:
+
+| Attribute | Type | Notes |
+|-----------|------|-------|
+| `day` | `Integer` | Day of month (0–31) |
+| `type` | `String` | The payment term type (see below) |
+
+### Payment term types
+
+| Type | Meaning |
+|------|---------|
+| `DAYSAFTERBILLDATE` | Day(s) after bill date |
+| `DAYSAFTERBILLMONTH` | Day(s) after bill month |
+| `OFCURRENTMONTH` | Of the current month |
+| `OFFOLLOWINGMONTH` | Of the following month |
+
+## Equality
+
+Two `PaymentTerms` are `==` if both their `bills` and `sales` are equal. Two
+`PaymentTerm` objects are `==` if they share the same `day` and `type`.
+
+## Serialisation
+
+```ruby
+org.payment_terms.to_h
+# => { bills: { day: 15, type: "OFCURRENTMONTH" }, sales: { day: 20, type: "OFFOLLOWINGMONTH" } }
+```

data/docs/accounting/payment.md

@@ -0,0 +1,99 @@
+# Payments
+
+A Xero **payment** records money received or paid against an invoice, credit
+note, prepayment, or overpayment. Payments can be applied to approved AR and AP
+invoices, and used to refund credit notes, prepayments, and overpayments. You
+need a `tenant_id` from a [connection](../connections.md) before you can fetch
+payments.
+
+> See: [Xero docs — Payments](https://developer.xero.com/documentation/api/accounting/payments)
+
+## Listing payments
+
+```ruby
+client = XeroKiwi::Client.new(access_token: "ya29...")
+
+# Pass a tenant ID string…
+payments = client.payments("70784a63-d24b-46a9-a4db-0e70a274b056")
+
+# …or a XeroKiwi::Connection (its tenant_id is used automatically).
+connection = client.connections.first
+payments = client.payments(connection)
+```
+
+`client.payments` hits `GET /api.xro/2.0/Payments` with the `Xero-Tenant-Id`
+header set to the tenant you specify. It returns an
+`Array<XeroKiwi::Accounting::Payment>`.
+
+## Fetching a single payment
+
+```ruby
+payment = client.payment(tenant_id, "b26fd49a-cbae-470a-a8f8-bcbc119e0379")
+payment.amount  # => 500.00
+```
+
+`client.payment` hits `GET /api.xro/2.0/Payments/{PaymentID}` and returns a
+single `XeroKiwi::Accounting::Payment`, or `nil` if the response is empty.
+
+## The Payment object
+
+Each `XeroKiwi::Accounting::Payment` is an immutable value object exposing the
+fields Xero returns:
+
+| Attribute | Type | What it is |
+|-----------|------|------------|
+| `payment_id` | `String` | The unique Xero identifier. |
+| `date` | `Time` | The date the payment was made, parsed as UTC. |
+| `currency_rate` | `Numeric` | Exchange rate (1.0 for base currency). |
+| `amount` | `Numeric` | The payment amount in the invoice's currency. |
+| `bank_amount` | `Numeric` | The payment amount in the account's currency. |
+| `reference` | `String` | An optional description for the payment. |
+| `is_reconciled` | `Boolean` | Whether the payment has been reconciled. |
+| `status` | `String` | e.g. `"AUTHORISED"`, `"DELETED"`. |
+| `payment_type` | `String` | e.g. `"ACCRECPAYMENT"`, `"ACCPAYPAYMENT"`. See Xero docs for all types. |
+| `updated_date_utc` | `Time` | When the payment was last modified, parsed as UTC. |
+| `batch_payment_id` | `String` | The batch payment ID, if created as part of a batch. |
+| `batch_payment` | `Hash` | Batch payment details (raw hash). |
+| `account` | `Hash` | The account the payment was made from (raw hash with `AccountID`, `Code`, `Name`). |
+| `invoice` | `Hash` | The invoice the payment was made against (raw hash). |
+| `credit_note` | `Hash` | The credit note being refunded (raw hash), if applicable. |
+| `prepayment` | `Hash` | The prepayment being refunded (raw hash), if applicable. |
+| `overpayment` | `Hash` | The overpayment being refunded (raw hash), if applicable. |
+| `has_account` | `Boolean` | Whether the payment has an associated account. |
+
+## Predicates
+
+```ruby
+payment.reconciled?  # is_reconciled == true
+```
+
+## Equality and hashing
+
+Two payments are `==` if they share the same `payment_id`. `#hash` is consistent
+with `==`, so payments work as hash keys and in sets.
+
+## Error behaviour
+
+| HTTP status | Exception | What it usually means |
+|-------------|-----------|------------------------|
+| 200 | (none — returns payments) | Success |
+| 401 | `XeroKiwi::AuthenticationError` | Access token is invalid or expired |
+| 403 | `XeroKiwi::ClientError` | The token doesn't have the required scope |
+| 404 | `XeroKiwi::ClientError` | The payment ID doesn't exist |
+
+## Common patterns
+
+### Listing reconciled payments
+
+```ruby
+payments = client.payments(tenant_id)
+reconciled = payments.select(&:reconciled?)
+reconciled.each { |p| puts "#{p.reference}: #{p.amount}" }
+```
+
+### Finding payments for a specific invoice
+
+```ruby
+payments = client.payments(tenant_id)
+for_invoice = payments.select { |p| p.invoice&.dig("InvoiceNumber") == "INV-0001" }
+```

data/docs/accounting/phone.md

@@ -0,0 +1,45 @@
+# XeroKiwi::Accounting::Phone
+
+A Xero phone number. Used by [Organisation](organisation.md), and in future by
+Contact and other resources.
+
+> See: [Xero docs — Phone types](https://developer.xero.com/documentation/api/accounting/types#phones)
+
+## Usage
+
+```ruby
+org.phones.each do |phone|
+  puts "#{phone.phone_type}: #{phone.phone_country_code} #{phone.phone_area_code} #{phone.phone_number}"
+end
+
+mobile = org.phones.find(&:mobile?)
+```
+
+## Attributes
+
+| Attribute | Type | Notes |
+|-----------|------|-------|
+| `phone_type` | `String` | `"DEFAULT"`, `"DDI"`, `"MOBILE"`, or `"FAX"` |
+| `phone_number` | `String` | Max 50 characters |
+| `phone_area_code` | `String` | Max 10 characters |
+| `phone_country_code` | `String` | Max 20 characters |
+
+## Predicates
+
+```ruby
+phone.default? # phone_type == "DEFAULT"
+phone.mobile?  # phone_type == "MOBILE"
+phone.fax?     # phone_type == "FAX"
+```
+
+## Equality
+
+Two phones are `==` if all their attributes match. `#hash` is consistent
+with `==`.
+
+## Serialisation
+
+```ruby
+phone.to_h
+# => { phone_type: "DEFAULT", phone_number: "1234567", phone_area_code: "09", phone_country_code: "64" }
+```