@epilot/sdk 2.1.0-rc.0 → 2.1.0

package/docs/billing.md

@@ -0,0 +1,783 @@
+# Billing API
+
+- **Base URL:** `https://billing.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/billing](https://docs.epilot.io/api/billing)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.billing.getBillingEvents(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/billing'
+
+const billingClient = getClient()
+authorize(billingClient, () => '<token>')
+const { data } = await billingClient.getBillingEvents(...)
+```
+
+## Operations
+
+**Billing Events**
+- [`getBillingEvents`](#getbillingevents)
+- [`createBillingEvent`](#createbillingevent)
+- [`getBillingEvent`](#getbillingevent)
+- [`updateBillingEvent`](#updatebillingevent)
+- [`deleteBillingEvent`](#deletebillingevent)
+- [`getBillingEventByExternalId`](#getbillingeventbyexternalid)
+
+**Contracts**
+- [`createContractEntity`](#createcontractentity)
+- [`updateContractEntity`](#updatecontractentity)
+- [`deleteContractEntity`](#deletecontractentity)
+
+**Balance**
+- [`getCustomerBalance`](#getcustomerbalance)
+
+**Schemas**
+- [`BaseEntity`](#baseentity)
+- [`EntityId`](#entityid)
+- [`EntitySlug`](#entityslug)
+- [`EntityRelationItem`](#entityrelationitem)
+- [`BaseBillingEvent`](#basebillingevent)
+- [`InstallmentEvent`](#installmentevent)
+- [`ReimbursementEvent`](#reimbursementevent)
+- [`BillingEvent`](#billingevent)
+- [`Contract`](#contract)
+- [`ContractItem`](#contractitem)
+- [`Balance`](#balance)
+- [`Currency`](#currency)
+
+### `getBillingEvents`
+
+Get and filter billing events such as installments and reimbursements.
+
+`GET /v1/billing/events`
+
+```ts
+const { data } = await client.getBillingEvents({
+  from: 1,
+  size: 1,
+  entity_id: ['...'],
+  event_type: 'example',
+  date_after: 'example',
+  date_before: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "hits": 0,
+  "results": [
+    {
+      "billing_amount": 10050,
+      "billing_amount_decimal": "100.50",
+      "billing_currency": "EUR",
+      "external_id": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e",
+      "contract": {
+        "$relation": [
+          {
+            "entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
+          }
+        ]
+      },
+      "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+      "_title": "string",
+      "_org": "string",
+      "_schema": "contact",
+      "_tags": ["string"],
+      "_created_at": "string",
+      "_updated_at": "string",
+      "type": "installment",
+      "due_date": "1970-01-01T00:00:00.000Z",
+      "paid_date": "1970-01-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `createBillingEvent`
+
+Create a new billing event.
+
+`POST /v1/billing/events`
+
+```ts
+const { data } = await client.createBillingEvent(
+  null,
+  {
+    billing_amount: 10050,
+    billing_amount_decimal: '100.50',
+    billing_currency: 'EUR',
+    external_id: 'd4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e',
+    contract: {
+      $relation: [
+        {
+          entity_id: 'f589786b-3024-43cd-9cb3-5a3c953f2896'
+        }
+      ]
+    },
+    _id: '5da0a718-c822-403d-9f5d-20d4584e0528',
+    _title: 'string',
+    _org: 'string',
+    _schema: 'contact',
+    _tags: ['string'],
+    _created_at: 'string',
+    _updated_at: 'string',
+    type: 'installment',
+    due_date: '1970-01-01T00:00:00.000Z',
+    paid_date: '1970-01-01T00:00:00.000Z'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "billing_amount": 10050,
+  "billing_amount_decimal": "100.50",
+  "billing_currency": "EUR",
+  "external_id": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e",
+  "contract": {
+    "$relation": [
+      {
+        "entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
+      }
+    ]
+  },
+  "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+  "_title": "string",
+  "_org": "string",
+  "_schema": "contact",
+  "_tags": ["string"],
+  "_created_at": "string",
+  "_updated_at": "string",
+  "type": "installment",
+  "due_date": "1970-01-01T00:00:00.000Z",
+  "paid_date": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
+### `getBillingEvent`
+
+Get a single billing event by ID.
+
+`GET /v1/billing/events/{id}`
+
+```ts
+const { data } = await client.getBillingEvent({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "billing_amount": 10050,
+  "billing_amount_decimal": "100.50",
+  "billing_currency": "EUR",
+  "external_id": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e",
+  "contract": {
+    "$relation": [
+      {
+        "entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
+      }
+    ]
+  },
+  "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+  "_title": "string",
+  "_org": "string",
+  "_schema": "contact",
+  "_tags": ["string"],
+  "_created_at": "string",
+  "_updated_at": "string",
+  "type": "installment",
+  "due_date": "1970-01-01T00:00:00.000Z",
+  "paid_date": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
+### `updateBillingEvent`
+
+Update an existing billing event.
+
+`PATCH /v1/billing/events/{id}`
+
+```ts
+const { data } = await client.updateBillingEvent(
+  {
+    id: '123e4567-e89b-12d3-a456-426614174000',
+  },
+  {
+    billing_amount: 10050,
+    billing_amount_decimal: '100.50',
+    billing_currency: 'EUR',
+    external_id: 'd4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e',
+    contract: {
+      $relation: [
+        {
+          entity_id: 'f589786b-3024-43cd-9cb3-5a3c953f2896'
+        }
+      ]
+    },
+    _id: '5da0a718-c822-403d-9f5d-20d4584e0528',
+    _title: 'string',
+    _org: 'string',
+    _schema: 'contact',
+    _tags: ['string'],
+    _created_at: 'string',
+    _updated_at: 'string',
+    type: 'installment',
+    due_date: '1970-01-01T00:00:00.000Z',
+    paid_date: '1970-01-01T00:00:00.000Z'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "billing_amount": 10050,
+  "billing_amount_decimal": "100.50",
+  "billing_currency": "EUR",
+  "external_id": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e",
+  "contract": {
+    "$relation": [
+      {
+        "entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
+      }
+    ]
+  },
+  "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+  "_title": "string",
+  "_org": "string",
+  "_schema": "contact",
+  "_tags": ["string"],
+  "_created_at": "string",
+  "_updated_at": "string",
+  "type": "installment",
+  "due_date": "1970-01-01T00:00:00.000Z",
+  "paid_date": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
+### `deleteBillingEvent`
+
+Delete an existing billing event.
+
+`DELETE /v1/billing/events/{id}`
+
+```ts
+const { data } = await client.deleteBillingEvent({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+---
+
+### `getBillingEventByExternalId`
+
+Get a single billing event by External ID.
+
+`GET /v1/billing/external/{external_id}`
+
+```ts
+const { data } = await client.getBillingEventByExternalId({
+  external_id: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "billing_amount": 10050,
+  "billing_amount_decimal": "100.50",
+  "billing_currency": "EUR",
+  "external_id": "d4fb2a4e-3f74-4fc4-8fba-6fdaaaa3b08e",
+  "contract": {
+    "$relation": [
+      {
+        "entity_id": "f589786b-3024-43cd-9cb3-5a3c953f2896"
+      }
+    ]
+  },
+  "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+  "_title": "string",
+  "_org": "string",
+  "_schema": "contact",
+  "_tags": ["string"],
+  "_created_at": "string",
+  "_updated_at": "string",
+  "type": "installment",
+  "due_date": "1970-01-01T00:00:00.000Z",
+  "paid_date": "1970-01-01T00:00:00.000Z"
+}
+```
+
+</details>
+
+---
+
+### `createContractEntity`
+
+Create a new contract entity.
+
+`POST /v1/billing/contracts`
+
+```ts
+const { data } = await client.createContractEntity(
+  null,
+  {
+    _id: '5da0a718-c822-403d-9f5d-20d4584e0528',
+    _title: 'string',
+    _org: 'string',
+    _schema: 'contact',
+    _tags: ['string'],
+    _created_at: 'string',
+    _updated_at: 'string',
+    contract_name: 'Grid Contract',
+    contract_number: '12345',
+    status: 'approved',
+    description: 'This contract is for the supply of widgets.',
+    account_number: '67890',
+    branch: 'power',
+    billing_address: '123 Main St, Anytown',
+    delivery_address: '456 Elm St, Anytown',
+    additional_addresses: '789 Oak St, Anytown',
+    termination_date: '2022-01-01',
+    termination_reason: 'Non-payment',
+    billing_period: 'monthly',
+    billing_duration_amount: 30,
+    renewal_duration_amount: 365,
+    renewal_duration_unit: 'years',
+    notice_time_amount: 30,
+    notice_time_unit: 'months',
+    start_date: '2021-01-01',
+    billing_due_day: 2,
+    installment_amount: 10050,
+    balance: 8990,
+    balance_currency: 'EUR'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+  "_title": "string",
+  "_org": "string",
+  "_schema": "contact",
+  "_tags": ["string"],
+  "_created_at": "string",
+  "_updated_at": "string",
+  "contract_name": "Grid Contract",
+  "contract_number": "12345",
+  "status": "approved",
+  "description": "This contract is for the supply of widgets.",
+  "account_number": "67890",
+  "branch": "power",
+  "billing_address": "123 Main St, Anytown",
+  "delivery_address": "456 Elm St, Anytown",
+  "additional_addresses": "789 Oak St, Anytown",
+  "termination_date": "2022-01-01",
+  "termination_reason": "Non-payment",
+  "billing_period": "monthly",
+  "billing_duration_amount": 30,
+  "renewal_duration_amount": 365,
+  "renewal_duration_unit": "years",
+  "notice_time_amount": 30,
+  "notice_time_unit": "months",
+  "start_date": "2021-01-01",
+  "billing_due_day": 2,
+  "installment_amount": 10050,
+  "balance": 8990,
+  "balance_currency": "EUR"
+}
+```
+
+</details>
+
+---
+
+### `updateContractEntity`
+
+Update an existing contract entity.
+
+`PATCH /v1/billing/contracts/{id}`
+
+```ts
+const { data } = await client.updateContractEntity(
+  {
+    id: '123e4567-e89b-12d3-a456-426614174000',
+  },
+  {
+    _id: '5da0a718-c822-403d-9f5d-20d4584e0528',
+    _title: 'string',
+    _org: 'string',
+    _schema: 'contact',
+    _tags: ['string'],
+    _created_at: 'string',
+    _updated_at: 'string',
+    contract_name: 'Grid Contract',
+    contract_number: '12345',
+    status: 'approved',
+    description: 'This contract is for the supply of widgets.',
+    account_number: '67890',
+    branch: 'power',
+    billing_address: '123 Main St, Anytown',
+    delivery_address: '456 Elm St, Anytown',
+    additional_addresses: '789 Oak St, Anytown',
+    termination_date: '2022-01-01',
+    termination_reason: 'Non-payment',
+    billing_period: 'monthly',
+    billing_duration_amount: 30,
+    renewal_duration_amount: 365,
+    renewal_duration_unit: 'years',
+    notice_time_amount: 30,
+    notice_time_unit: 'months',
+    start_date: '2021-01-01',
+    billing_due_day: 2,
+    installment_amount: 10050,
+    balance: 8990,
+    balance_currency: 'EUR'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "_id": "5da0a718-c822-403d-9f5d-20d4584e0528",
+  "_title": "string",
+  "_org": "string",
+  "_schema": "contact",
+  "_tags": ["string"],
+  "_created_at": "string",
+  "_updated_at": "string",
+  "contract_name": "Grid Contract",
+  "contract_number": "12345",
+  "status": "approved",
+  "description": "This contract is for the supply of widgets.",
+  "account_number": "67890",
+  "branch": "power",
+  "billing_address": "123 Main St, Anytown",
+  "delivery_address": "456 Elm St, Anytown",
+  "additional_addresses": "789 Oak St, Anytown",
+  "termination_date": "2022-01-01",
+  "termination_reason": "Non-payment",
+  "billing_period": "monthly",
+  "billing_duration_amount": 30,
+  "renewal_duration_amount": 365,
+  "renewal_duration_unit": "years",
+  "notice_time_amount": 30,
+  "notice_time_unit": "months",
+  "start_date": "2021-01-01",
+  "billing_due_day": 2,
+  "installment_amount": 10050,
+  "balance": 8990,
+  "balance_currency": "EUR"
+}
+```
+
+</details>
+
+---
+
+### `deleteContractEntity`
+
+Delete an existing contract entity.
+
+`DELETE /v1/billing/contracts/{id}`
+
+```ts
+const { data } = await client.deleteContractEntity({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+---
+
+### `getCustomerBalance`
+
+Get total balance across all contracts and orders of a customer entity.
+
+`GET /v1/billing/customers/{id}/balance`
+
+```ts
+const { data } = await client.getCustomerBalance({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "balance": 8990,
+  "balance_decimal": "89.90",
+  "balance_currency": "EUR"
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `BaseEntity`
+
+```ts
+type BaseEntity = {
+  _id?: string
+  _title?: string
+  _org?: string
+  _schema?: "contact" | "contract" | "file" | "order" | "opportunity" | "product" | "price" | "meter" | "meter_counter" | "billing_event"
+  _tags?: string[]
+  _created_at?: string
+  _updated_at?: string
+}
+```
+
+### `EntityId`
+
+Entity ID
+
+```ts
+type EntityId = string
+```
+
+### `EntitySlug`
+
+URL-friendly identifier for the entity schema
+
+```ts
+type EntitySlug = "contact" | "contract" | "file" | "order" | "opportunity" | "product" | "price" | "meter" | "meter_counter" | "billing_event"
+```
+
+### `EntityRelationItem`
+
+```ts
+type EntityRelationItem = {
+  entity_id?: string
+}
+```
+
+### `BaseBillingEvent`
+
+A base billing event to be inherited by all billing events.
+
+```ts
+type BaseBillingEvent = {
+  _id?: string
+  _title?: string
+  _org?: string
+  _schema?: "contact" | "contract" | "file" | "order" | "opportunity" | "product" | "price" | "meter" | "meter_counter" | "billing_event"
+  _tags?: string[]
+  _created_at?: string
+  _updated_at?: string
+}
+```
+
+### `InstallmentEvent`
+
+An entity that describes an installment billing event.
+
+```ts
+type InstallmentEvent = {
+  billing_amount: number
+  billing_amount_decimal: string
+  billing_currency: string
+  external_id?: string
+  contract: {
+    $relation?: Array<{
+      entity_id?: { ... }
+    }>
+  }
+  type: "installment"
+  due_date: string // date-time
+  paid_date?: string // date-time
+}
+```
+
+### `ReimbursementEvent`
+
+An entity that describes a reimbursement billing event.
+
+```ts
+type ReimbursementEvent = {
+  billing_amount: number
+  billing_amount_decimal: string
+  billing_currency: string
+  external_id?: string
+  contract: {
+    $relation?: Array<{
+      entity_id?: { ... }
+    }>
+  }
+  type: "reimbursement"
+  paid_date?: string // date-time
+}
+```
+
+### `BillingEvent`
+
+An entity that describes a billing event such as a future installment or a reimbursement back to the customer.
+
+```ts
+type BillingEvent = {
+  billing_amount: number
+  billing_amount_decimal: string
+  billing_currency: string
+  external_id?: string
+  contract: {
+    $relation?: Array<{
+      entity_id?: { ... }
+    }>
+  }
+  type: "installment"
+  due_date: string // date-time
+  paid_date?: string // date-time
+} | {
+  billing_amount: number
+  billing_amount_decimal: string
+  billing_currency: string
+  external_id?: string
+  contract: {
+    $relation?: Array<{
+      entity_id?: { ... }
+    }>
+  }
+  type: "reimbursement"
+  paid_date?: string // date-time
+}
+```
+
+### `Contract`
+
+```ts
+type Contract = {
+  _id?: string
+  _title?: string
+  _org?: string
+  _schema?: "contact" | "contract" | "file" | "order" | "opportunity" | "product" | "price" | "meter" | "meter_counter" | "billing_event"
+  _tags?: string[]
+  _created_at?: string
+  _updated_at?: string
+  contract_name?: string
+  contract_number?: string
+  status?: "draft" | "in_approval_process" | "approved" | "active" | "deactivated" | "revoked" | "terminated" | "expired"
+  description?: string
+  account_number?: string
+  branch?: "power" | "gas" | "water" | "waste_water" | "district_heating"
+  billing_address?: string
+  delivery_address?: string
+  additional_addresses?: string
+  termination_date?: string
+  termination_reason?: string
+  billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly"
+  billing_duration_amount?: number
+  renewal_duration_amount?: number
+  renewal_duration_unit?: "weeks" | "months" | "years"
+  notice_time_amount?: number
+  notice_time_unit?: "weeks" | "months" | "years"
+  start_date?: string
+  billing_due_day?: number
+  installment_amount?: number
+  balance?: number
+  balance_currency?: string
+}
+```
+
+### `ContractItem`
+
+```ts
+type ContractItem = {
+  _id?: string
+  _title?: string
+  _org?: string
+  _schema?: "contact" | "contract" | "file" | "order" | "opportunity" | "product" | "price" | "meter" | "meter_counter" | "billing_event"
+  _tags?: string[]
+  _created_at?: string
+  _updated_at?: string
+  contract_name?: string
+  contract_number?: string
+  status?: "draft" | "in_approval_process" | "approved" | "active" | "deactivated" | "revoked" | "terminated" | "expired"
+  description?: string
+  account_number?: string
+  branch?: "power" | "gas" | "water" | "waste_water" | "district_heating"
+  billing_address?: string
+  delivery_address?: string
+  additional_addresses?: string
+  termination_date?: string
+  termination_reason?: string
+  billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly"
+  billing_duration_amount?: number
+  renewal_duration_amount?: number
+  renewal_duration_unit?: "weeks" | "months" | "years"
+  notice_time_amount?: number
+  notice_time_unit?: "weeks" | "months" | "years"
+  start_date?: string
+  billing_due_day?: number
+  installment_amount?: number
+  balance?: number
+  balance_currency?: string
+}
+```
+
+### `Balance`
+
+```ts
+type Balance = {
+  balance?: number
+  balance_decimal?: string
+  balance_currency?: string
+}
+```
+
+### `Currency`
+
+Currency code in ISO 4217 format
+
+```ts
+type Currency = string
+```