# `MishkaPay.Providers.Stripe.TestClock`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/providers/__stripe/test_clock.ex#L5)

Stripe's test clocks, to see what time does to a subscription in a sandbox: a trial that ends, a
renewal that is paid or fails, retries that run out. A customer made on a clock lives on its time;
moving the clock forward makes Stripe run everything that would have happened by then.

    {:ok, clock} = TestClock.create("site-a", name: "renewal test")
    # make a customer with test_clock: clock.id, and a subscription for them
    {:ok, clock} = TestClock.advance("site-a", clock.id, DateTime.add(clock.frozen_time, 32, :day))
    # Stripe moves it on its own servers: read it until `status: :ready`, then read the
    # subscription again (MishkaPay.fetch_subscription/3)

Only with a site's test keys: keys in `:live` mode, or a `sk_live_` or `rk_live_` key, are
refused before any request. Each call takes the tenant whose keys to use.

# `t`

```elixir
@type t() :: %MishkaPay.Providers.Stripe.TestClock{
  created_at: DateTime.t() | nil,
  frozen_time: DateTime.t() | nil,
  id: String.t(),
  name: String.t() | nil,
  status: (:ready | :advancing | :failed) | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:id` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)` |
| `:name` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:frozen_time` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:status` | `:ready` \| `:advancing` \| `:failed` \| `nil` | no |  |  | `validate(enum=Atom[ready::advancing::failed])` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `advance`

```elixir
@spec advance(term(), String.t(), DateTime.t()) ::
  {:ok, t()} | {:error, Splode.Error.t()}
```

Moves clock `id` forward to `to`. Stripe answers at once with `status: :advancing` and moves it
on its own servers; read it with `fetch/2` until it is `:ready`.

# `builder`

# `create`

```elixir
@spec create(term(), keyword()) :: {:ok, t()} | {:error, Splode.Error.t()}
```

Makes a clock frozen at `:at` (now by default), with an optional `:name`.

# `delete`

```elixir
@spec delete(term(), String.t()) :: :ok | {:error, Splode.Error.t()}
```

Deletes clock `id`, and with it every customer and subscription on it.

# `enforce_keys`

# `enforce_keys`

# `example`

A sample %MishkaPay.Providers.Stripe.TestClock{} populated from defaults + type-based fallbacks.

# `fetch`

```elixir
@spec fetch(term(), String.t()) :: {:ok, t()} | {:error, Splode.Error.t()}
```

Reads clock `id` again: its time and whether it has finished moving (`:ready`).

# `keys`

# `keys`

# `list`

```elixir
@spec list(term()) :: {:ok, [t()]} | {:error, Splode.Error.t()}
```

The site's clocks, newest first.

---

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