@epilot/sdk 2.1.0-rc.1 → 2.1.0

package/docs/address.md

@@ -0,0 +1,284 @@
+# Address API
+
+- **Base URL:** `https://address.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/address](https://docs.epilot.io/api/address)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.address.getAddressSuggestions(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/address'
+
+const addressClient = getClient()
+authorize(addressClient, () => '<token>')
+const { data } = await addressClient.getAddressSuggestions(...)
+```
+
+## Operations
+
+**Address Suggestion**
+- [`getAddressSuggestions`](#getaddresssuggestions)
+
+**Availability**
+- [`availabilityCheck`](#availabilitycheck)
+- [`validateAvailabilityFile`](#validateavailabilityfile)
+
+**Schemas**
+- [`AvailabilityCheckParams`](#availabilitycheckparams)
+- [`AvailabilityFilters`](#availabilityfilters)
+- [`AvailabilityDate`](#availabilitydate)
+- [`AvailabilityLocation`](#availabilitylocation)
+- [`AvailabilityResult`](#availabilityresult)
+- [`ValidateAvailabilityFileResult`](#validateavailabilityfileresult)
+- [`ValidateAvailabilityFileError`](#validateavailabilityfileerror)
+- [`AddressSuggestion`](#addresssuggestion)
+- [`AddressSuggestions`](#addresssuggestions)
+- [`ErrorResponse`](#errorresponse)
+
+### `getAddressSuggestions`
+
+Get address suggestions for the given Availability File
+
+`GET /v1/public/suggestions`
+
+```ts
+const { data } = await client.getAddressSuggestions({
+  fileRef: 'example',
+  countryCodeSearchTerm: 'example',
+  postalCodeSearchTerm: 'example',
+  streetSearchTerm: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "country": "st",
+    "postal_code": "string",
+    "city": "string",
+    "street": "string",
+    "street_number": "string"
+  }
+]
+```
+
+</details>
+
+---
+
+### `availabilityCheck`
+
+Check for Entities that contain a matching availability range in related availability files.
+
+`POST /v1/public/availability`
+
+```ts
+const { data } = await client.availabilityCheck(
+  null,
+  {},
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "available_entities": [],
+  "check_results": [
+    {
+      "entity_id": "72c803b2-2e5d-4bd6-bffc-fad998bbbe36",
+      "matching_hits": 0
+    },
+    {
+      "entity_id": "72c803b2-2e5d-4bd6-bffc-fad998bbbe37",
+      "matching_hits": 0
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `validateAvailabilityFile`
+
+Validates an already uploaded availability file, it returns an array of errors if any errors are found in the file.
+
+`GET /v1/availability/{id}/validate`
+
+```ts
+const { data } = await client.validateAvailabilityFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "status": "success",
+  "rules_parsed_count": 0,
+  "errors": [
+    {
+      "line": 0,
+      "message": "string",
+      "data": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `AvailabilityCheckParams`
+
+```ts
+type AvailabilityCheckParams = {
+  entities: string // uuid[]
+  schemas?: string[]
+  filters: {
+    location: {
+      street?: { ... }
+      street_number?: { ... }
+      postal_code?: { ... }
+      city?: { ... }
+      country?: { ... }
+    }
+    available_date?: string // date
+  }
+}
+```
+
+### `AvailabilityFilters`
+
+Availability filters dimensions
+
+```ts
+type AvailabilityFilters = {
+  location: {
+    street?: string
+    street_number?: string
+    postal_code?: string
+    city?: string
+    country?: string
+  }
+  available_date?: string // date
+}
+```
+
+### `AvailabilityDate`
+
+A value to be matched against the availability window (start & end date)
+
+```ts
+type AvailabilityDate = string // date
+```
+
+### `AvailabilityLocation`
+
+```ts
+type AvailabilityLocation = {
+  street?: string
+  street_number?: string
+  postal_code?: string
+  city?: string
+  country?: string
+}
+```
+
+### `AvailabilityResult`
+
+The availability check result payload
+
+```ts
+type AvailabilityResult = {
+  available_entities: string[]
+  check_results: Array<{
+    entity_id: string // uuid
+    matching_hits: number
+    matching_error?: object
+  }>
+}
+```
+
+### `ValidateAvailabilityFileResult`
+
+The availability map file result payload
+
+```ts
+type ValidateAvailabilityFileResult = {
+  status: "success" | "error"
+  rules_parsed_count: number
+  errors: Array<{
+    line?: number
+    message: string
+    data?: string
+  }>
+}
+```
+
+### `ValidateAvailabilityFileError`
+
+The availability rule error
+
+```ts
+type ValidateAvailabilityFileError = {
+  line?: number
+  message: string
+  data?: string
+}
+```
+
+### `AddressSuggestion`
+
+The address suggestions entity
+
+```ts
+type AddressSuggestion = {
+  country?: string
+  postal_code?: string // postal-code
+  city?: string // city
+  street?: string // street-address
+  street_number?: string // street-number
+}
+```
+
+### `AddressSuggestions`
+
+The address suggestions entity array
+
+```ts
+type AddressSuggestions = Array<{
+  country?: string
+  postal_code?: string // postal-code
+  city?: string // city
+  street?: string // street-address
+  street_number?: string // street-number
+}>
+```
+
+### `ErrorResponse`
+
+```ts
+type ErrorResponse = {
+  error: string
+}
+```