@epilot/sdk 2.1.0-rc.1 → 2.1.0

package/docs/access-token.md

@@ -0,0 +1,440 @@
+# Access Token API
+
+- **Base URL:** `https://access-token.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/access-token](https://docs.epilot.io/api/access-token)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.accessToken.createAccessToken(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/access-token'
+
+const accessTokenClient = getClient()
+authorize(accessTokenClient, () => '<token>')
+const { data } = await accessTokenClient.createAccessToken(...)
+```
+
+## Operations
+
+**Access Tokens**
+- [`createAccessToken`](#createaccesstoken)
+- [`listAccessTokens`](#listaccesstokens)
+- [`revokeAccessToken`](#revokeaccesstoken)
+
+**Public**
+- [`getAccessTokenJwks`](#getaccesstokenjwks)
+- [`getAccessTokenOIDC`](#getaccesstokenoidc)
+- [`getPublicTokenJwks`](#getpublictokenjwks)
+- [`getPublicTokenOIDC`](#getpublictokenoidc)
+
+**Schemas**
+- [`AccessToken`](#accesstoken)
+- [`AccessTokenId`](#accesstokenid)
+- [`AccessTokenName`](#accesstokenname)
+- [`AccessTokenType`](#accesstokentype)
+- [`AccessTokenJourneyId`](#accesstokenjourneyid)
+- [`PortalId`](#portalid)
+- [`TokenParameters`](#tokenparameters)
+- [`ExpiresIn`](#expiresin)
+- [`AccessTokenParameters`](#accesstokenparameters)
+- [`JourneyTokenParameters`](#journeytokenparameters)
+- [`PortalTokenParameters`](#portaltokenparameters)
+- [`AssumeTokenParameters`](#assumetokenparameters)
+- [`AppTokenParameters`](#apptokenparameters)
+- [`AccessTokenItem`](#accesstokenitem)
+- [`RoleId`](#roleid)
+- [`Assignments`](#assignments)
+
+### `createAccessToken`
+
+**Access Token type: `API`** (default if not specified):
+
+`POST /v1/access-tokens`
+
+```ts
+const { data } = await client.createAccessToken(
+  null,
+  {
+    name: 'Postman Access Token',
+    token_type: 'api',
+    assignments: ['123:owner'],
+    expires_in: 3600
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
+  "id": "api_5ZugdRXasLfWBypHi93Fk",
+  "created_at": "1970-01-01T00:00:00.000Z",
+  "name": "Postman Access Token",
+  "token_type": "api",
+  "journey_id": "string",
+  "portal_id": "string",
+  "assignments": ["123:owner"],
+  "last_used": "2026-02-24"
+}
+```
+
+</details>
+
+---
+
+### `listAccessTokens`
+
+Lists all Access Tokens for current user (by default excludes system generated tokens)
+
+`GET /v1/access-tokens`
+
+```ts
+const { data } = await client.listAccessTokens({
+  token_type: ['...'],
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "id": "api_5ZugdRXasLfWBypHi93Fk",
+    "created_at": "1970-01-01T00:00:00.000Z",
+    "name": "Postman Access Token",
+    "token_type": "api",
+    "journey_id": "string",
+    "portal_id": "string",
+    "assignments": ["123:owner"],
+    "last_used": "2026-02-24"
+  }
+]
+```
+
+</details>
+
+---
+
+### `revokeAccessToken`
+
+Revokes an Access Token so it can't be used anymore.
+
+`DELETE /v1/access-tokens/{id}`
+
+```ts
+const { data } = await client.revokeAccessToken({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "api_5ZugdRXasLfWBypHi93Fk",
+  "created_at": "1970-01-01T00:00:00.000Z",
+  "name": "Postman Access Token",
+  "token_type": "api",
+  "journey_id": "string",
+  "portal_id": "string",
+  "assignments": ["123:owner"],
+  "last_used": "2026-02-24"
+}
+```
+
+</details>
+
+---
+
+### `getAccessTokenJwks`
+
+Get jwks public key set to verify access tokens generated by this API
+
+`GET /v1/access-tokens/.well-known/jwks.json`
+
+```ts
+const { data } = await client.getAccessTokenJwks()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "keys": [
+    {
+      "alg": "RS256",
+      "e": "AQAB",
+      "kid": "tXWU5mPMbRPczpbQwi6vbhLF4GgF3wlMDSyqo7pfeiw=",
+      "kty": "RSA",
+      "n": "h_QDoCjZ8W_trtYXaP7_S22wf5r5Wd9XBLED78oT44bJjQXn8ddcFV8Hik65_4IYXVX_hTTU4zpxe3H8vx2j7-Zz3O59mYMp5S0MzODNEdf5Y_2o19eis0brmAJniixsNlQ9LlYkdrVamrgaxHu3ZpP_99zkfFybYeuYoQNzb3PyrT8xVnz_USs_nlFMHpGUxvvz7gfKPqxcLvgLJr4cwI9yzaSY9CD4qW181QVcnL_WzpQ8xx6AuhhHZQ1l_3GG4InTk8ahE7U2ZHVu8RrX6d01pMgc3piEcet9RgFLnhbTg3YIiKGoAbN42wJn_x3lgIAC42T9mbmTsHyUdS6nUQ",
+      "use": "sig"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `getAccessTokenOIDC`
+
+OpenID Connect configuration for Access Token API as identity provider
+
+`GET /v1/access-tokens/.well-known/openid-configuration`
+
+```ts
+const { data } = await client.getAccessTokenOIDC()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "issuer": "https://access-token.sls.epilot.io/v1/access-tokens",
+  "jwks_uri": "https://access-token.sls.epilot.io/v1/access-tokens/.well-known/jwks.json"
+}
+```
+
+</details>
+
+---
+
+### `getPublicTokenJwks`
+
+Get jwks public key set to verify public tokens generated by this API
+
+`GET /v1/access-tokens/public/.well-known/jwks.json`
+
+```ts
+const { data } = await client.getPublicTokenJwks()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "keys": [
+    {
+      "alg": "RS256",
+      "e": "AQAB",
+      "kid": "tXWU5mPMbRPczpbQwi6vbhLF4GgF3wlMDSyqo7pfeiw=",
+      "kty": "RSA",
+      "n": "h_QDoCjZ8W_trtYXaP7_S22wf5r5Wd9XBLED78oT44bJjQXn8ddcFV8Hik65_4IYXVX_hTTU4zpxe3H8vx2j7-Zz3O59mYMp5S0MzODNEdf5Y_2o19eis0brmAJniixsNlQ9LlYkdrVamrgaxHu3ZpP_99zkfFybYeuYoQNzb3PyrT8xVnz_USs_nlFMHpGUxvvz7gfKPqxcLvgLJr4cwI9yzaSY9CD4qW181QVcnL_WzpQ8xx6AuhhHZQ1l_3GG4InTk8ahE7U2ZHVu8RrX6d01pMgc3piEcet9RgFLnhbTg3YIiKGoAbN42wJn_x3lgIAC42T9mbmTsHyUdS6nUQ",
+      "use": "sig"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `getPublicTokenOIDC`
+
+OpenID Connect configuration for Access Token API a a public identity provider
+
+`GET /v1/access-tokens/public/.well-known/openid-configuration`
+
+```ts
+const { data } = await client.getPublicTokenOIDC()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "issuer": "https://access-token.sls.epilot.io/v1/access-tokens",
+  "jwks_uri": "https://access-token.sls.epilot.io/v1/access-tokens/.well-known/jwks.json"
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `AccessToken`
+
+A JWT Access Token
+
+```ts
+type AccessToken = string
+```
+
+### `AccessTokenId`
+
+```ts
+type AccessTokenId = string
+```
+
+### `AccessTokenName`
+
+Human readable name for access token
+
+```ts
+type AccessTokenName = string
+```
+
+### `AccessTokenType`
+
+Access token type
+
+```ts
+type AccessTokenType = "api" | "journey" | "portal" | "assume" | "app"
+```
+
+### `AccessTokenJourneyId`
+
+Journey ID for access token type "journey"
+
+```ts
+type AccessTokenJourneyId = string
+```
+
+### `PortalId`
+
+Portal ID for access token type "portal"
+
+```ts
+type PortalId = string
+```
+
+### `TokenParameters`
+
+```ts
+type TokenParameters = {
+  name: string
+  token_type?: "api"
+  assignments?: string[]
+  expires_in?: number | string
+} | {
+  name: string
+  token_type?: "journey"
+  journey_id: string
+  expires_in?: number | string
+} | {
+  name: string
+  token_type?: "portal"
+  portal_id: string
+  expires_in?: number | string
+} | {
+  name: string
+  token_type?: "assume"
+  assignments?: string[]
+} | {
+  name: string
+  token_type?: "app"
+  assignments?: string[]
+  expires_in?: number | string
+}
+```
+
+### `ExpiresIn`
+
+```ts
+type ExpiresIn = number | string
+```
+
+### `AccessTokenParameters`
+
+```ts
+type AccessTokenParameters = {
+  name: string
+  token_type?: "api"
+  assignments?: string[]
+  expires_in?: number | string
+}
+```
+
+### `JourneyTokenParameters`
+
+```ts
+type JourneyTokenParameters = {
+  name: string
+  token_type?: "journey"
+  journey_id: string
+  expires_in?: number | string
+}
+```
+
+### `PortalTokenParameters`
+
+```ts
+type PortalTokenParameters = {
+  name: string
+  token_type?: "portal"
+  portal_id: string
+  expires_in?: number | string
+}
+```
+
+### `AssumeTokenParameters`
+
+```ts
+type AssumeTokenParameters = {
+  name: string
+  token_type?: "assume"
+  assignments?: string[]
+}
+```
+
+### `AppTokenParameters`
+
+```ts
+type AppTokenParameters = {
+  name: string
+  token_type?: "app"
+  assignments?: string[]
+  expires_in?: number | string
+}
+```
+
+### `AccessTokenItem`
+
+```ts
+type AccessTokenItem = {
+  id: string
+  created_at: string // date-time
+  name: string
+  token_type?: "api" | "journey" | "portal" | "assume" | "app"
+  journey_id?: string
+  portal_id?: string
+  assignments?: string[]
+  last_used?: string // date
+}
+```
+
+### `RoleId`
+
+Format: `<organization_id>`:`<slug>`
+
+```ts
+type RoleId = string
+```
+
+### `Assignments`
+
+List of role ids attached to an user
+
+```ts
+type Assignments = string[]
+```

package/docs/address-suggestions.md

@@ -0,0 +1,256 @@
+# Address Suggestions API
+
+- **Base URL:** `https://address-suggestions-api.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/address-suggestions](https://docs.epilot.io/api/address-suggestions)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.addressSuggestions.getAddresses(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/address-suggestions'
+
+const addressSuggestionsClient = getClient()
+authorize(addressSuggestionsClient, () => '<token>')
+const { data } = await addressSuggestionsClient.getAddresses(...)
+```
+
+## Operations
+
+**Addresses API**
+- [`getAddresses`](#getaddresses)
+- [`checkAvailability`](#checkavailability)
+- [`validateAddressesFile`](#validateaddressesfile)
+
+**Schemas**
+- [`AvailabilityLocation`](#availabilitylocation)
+- [`AvailabilityResult`](#availabilityresult)
+- [`Error`](#error)
+- [`AddressSuggestion`](#addresssuggestion)
+- [`AddressSuggestions`](#addresssuggestions)
+- [`ValidateAddressSuggestionsFileResult`](#validateaddresssuggestionsfileresult)
+- [`ValidateAddressFileResult`](#validateaddressfileresult)
+- [`AddressSuggestionError`](#addresssuggestionerror)
+- [`ValidateAddressFileError`](#validateaddressfileerror)
+
+### `getAddresses`
+
+get addresses from file
+
+`GET /v1/public/suggestions`
+
+```ts
+const { data } = await client.getAddresses({
+  X-Epilot-Org-ID: 'example',
+  s3FileUrl: 'example',
+  fileId: 'example',
+  countryCodeSearchTerm: 'example',
+  postalCodeSearchTerm: 'example',
+  streetSearchTerm: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "country": "string",
+    "postal_code": "string",
+    "city": "string",
+    "street": "string",
+    "street_number": "string"
+  }
+]
+```
+
+</details>
+
+---
+
+### `checkAvailability`
+
+Check address availability
+
+`GET /v1/public/availability:check`
+
+```ts
+const { data } = await client.checkAvailability({
+  X-Epilot-Org-ID: 'example',
+  files: 'example',
+  countryCode: 'example',
+  postalCode: 'example',
+  street: 'example',
+  streetNumber: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "fileId": "4e7b7d95-ced6-4f5f-9326-0c61f30dcadb"
+}
+```
+
+</details>
+
+---
+
+### `validateAddressesFile`
+
+validate addresses file
+
+`GET /v1/addresses-files:validate`
+
+```ts
+const { data } = await client.validateAddressesFile({
+  fileId: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "status": "success",
+  "rules_parsed_count": 0,
+  "errors": [
+    {
+      "line": 0,
+      "msg": "string",
+      "data": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `AvailabilityLocation`
+
+```ts
+type AvailabilityLocation = {
+  street?: string
+  street_number?: string
+  postal_code?: string
+  city?: string
+  country?: string
+}
+```
+
+### `AvailabilityResult`
+
+```ts
+type AvailabilityResult = {
+  fileId?: string
+}
+```
+
+### `Error`
+
+```ts
+type Error = {
+  message: string
+  status?: number
+  cause?: string
+}
+```
+
+### `AddressSuggestion`
+
+The address suggestions entity
+
+```ts
+type AddressSuggestion = {
+  country?: string
+  postal_code?: string
+  city?: string
+  street?: string
+  street_number?: string
+}
+```
+
+### `AddressSuggestions`
+
+The address suggestions entity array
+
+```ts
+type AddressSuggestions = Array<{
+  country?: string
+  postal_code?: string
+  city?: string
+  street?: string
+  street_number?: string
+}>
+```
+
+### `ValidateAddressSuggestionsFileResult`
+
+The availability map file result payload
+
+```ts
+type ValidateAddressSuggestionsFileResult = {
+  status?: "success" | "error"
+  rules_parsed_count?: number
+  errors?: Array<{
+    line?: number
+    msg: string
+    data?: string
+  }>
+}
+```
+
+### `ValidateAddressFileResult`
+
+The address file validation result payload
+
+```ts
+type ValidateAddressFileResult = {
+  status?: "success" | "error"
+  rules_parsed_count?: number
+  errors?: Array<{
+    line?: number
+    msg: string
+    data?: string
+  }>
+}
+```
+
+### `AddressSuggestionError`
+
+The availability rule error
+
+```ts
+type AddressSuggestionError = {
+  line?: number
+  msg: string
+  data?: string
+}
+```
+
+### `ValidateAddressFileError`
+
+The address rule error
+
+```ts
+type ValidateAddressFileError = {
+  line?: number
+  msg: string
+  data?: string
+}
+```