# `PolarExpress`
[🔗](https://github.com/jeffhuen/polar_express/blob/main/lib/polar_express.ex#L1)

Elixir SDK and client for the Polar API.

## Configuration

PolarExpress does not read application configuration. Read credentials from
your own application boundary, then pass them explicitly when creating a
client:

    client = PolarExpress.client(System.fetch_env!("POLAR_ACCESS_TOKEN"))

    {:ok, customer} = PolarExpress.Services.CustomersService.create_customer(client, %{
      email: "jane@example.com"
    })

## Finch Supervision

The default client uses a Finch pool named `PolarExpress.Finch`. Add
`PolarExpress` to your supervision tree, or pass a custom Finch name with
`:finch`:

    children = [
      PolarExpress
    ]

## Per-Client Options

Override any client option when creating a client:

    client = PolarExpress.client("pk_test_...", server: :sandbox)
    client = PolarExpress.client(api_key: "pk_test_...", max_retries: 5)

Options are resolved from explicit arguments and `PolarExpress.Client` struct
defaults only.

## Supported Client Options

  * `:api_key` - Polar API key (required)
  * `:server` - API environment: `:production` or `:sandbox` (default: `:production`)
  * `:max_retries` - Maximum retry attempts (default: 2)
  * `:timeout_ms` - Request timeout in ms (default: 30_000)
  * `:finch` - Custom Finch instance name (default: `PolarExpress.Finch`)

# `client_opts`

```elixir
@type client_opts() :: [
  api_key: String.t(),
  server: PolarExpress.Client.server(),
  base_url: String.t(),
  max_retries: non_neg_integer(),
  timeout_ms: pos_integer(),
  finch: atom()
]
```

# `benefit_grants`

Get BenefitGrantsService module

# `benefits`

Get BenefitsService module

# `checkout_links`

Get CheckoutLinksService module

# `checkouts`

Get CheckoutsService module

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

Returns the child spec for the default Finch pool.

Add this to your supervision tree when using the default
`PolarExpress.Finch` pool:

    children = [
      PolarExpress
    ]

Pass Finch options directly when you need to customize the pool:

    {PolarExpress, name: MyApp.PolarFinch}

# `client`

```elixir
@spec client() :: no_return()
```

Raises because PolarExpress clients require explicit credentials.

Use `client/1` or `client/2` instead:

    client = PolarExpress.client("pk_test_...")

# `client`

```elixir
@spec client(String.t() | client_opts()) :: PolarExpress.Client.t()
```

Create a new PolarExpress client.

When given a string, treated as an explicit API key.
When given a keyword list, `:api_key` must be present.

## Examples

    client = PolarExpress.client("pk_test_...")
    client = PolarExpress.client(api_key: "pk_test_...", server: :sandbox)

# `client`

```elixir
@spec client(
  String.t(),
  keyword()
) :: PolarExpress.Client.t()
```

Create a new PolarExpress client with an explicit API key.

# `custom_fields`

Get CustomFieldsService module

# `customer_meters`

Get CustomerMetersService module

# `customer_portal`

Get CustomerPortal namespace with 12 sub-services

# `customer_seats`

Get CustomerSeatsService module

# `customer_sessions`

Get CustomerSessionsService module

# `customers`

Get CustomersService module

# `discounts`

Get DiscountsService module

# `disputes`

Get DisputesService module

# `event_types`

Get EventTypesService module

# `events`

Get EventsService module

# `files`

Get FilesService module

# `license_keys`

Get LicenseKeysService module

# `member_sessions`

Get MemberSessionsService module

# `members`

Get MembersService module

# `meters`

Get MetersService module

# `metrics`

Get MetricsService module

# `oauth2`

Get Oauth2Service module

# `orders`

Get OrdersService module

# `organization_access_tokens`

Get OrganizationAccessTokensService module

# `organizations`

Get OrganizationsService module

# `payments`

Get PaymentsService module

# `products`

Get ProductsService module

# `refunds`

Get RefundsService module

# `subscriptions`

Get SubscriptionsService module

# `version`

```elixir
@spec version() :: String.t()
```

Returns the library version.

# `webhooks`

Get WebhooksService module

---

*Consult [api-reference.md](api-reference.md) for complete listing*