@spec advance(LatticeStripe.Client.t(), String.t(), integer(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Advances a Test Clock to a new frozen_time.

Sends POST /v1/test_helpers/test_clocks/:id/advance. The returned clock will typically have status: :advancing — the server processes the advancement asynchronously. Use advance_and_wait/4 (or the bang variant) if you need to block until the clock reaches :ready.

Stripe enforces a maximum advancement of roughly two billing intervals of the shortest attached subscription. Advancing further in a single call returns a 400 error; advance in chunks instead.

Parameters

• client — A %LatticeStripe.Client{} struct
• id — Test Clock id ("clock_...")
• frozen_time — Unix timestamp (integer) to advance TO
• opts — Per-request overrides

Returns

• {:ok, %TestClock{status: :advancing}} (usually) on success
• {:error, %LatticeStripe.Error{}} on failure

@spec advance!(LatticeStripe.Client.t(), String.t(), integer(), keyword()) ::
  t() | no_return()

Bang variant of advance/4. Returns %TestClock{} on success, raises LatticeStripe.Error on failure.

@spec advance_and_wait(LatticeStripe.Client.t(), String.t(), integer(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Advances a Test Clock and polls until it reaches status: :ready.

This is the differentiating helper for Stripe test-clock workflows: you almost never want to call advance/4 directly in a test, because the clock returns status: :advancing and you have to poll for completion yourself. advance_and_wait/4 does the advance + the polling + the terminal-failure detection + a well-behaved timeout, returning either a ready clock or a typed %LatticeStripe.Error{}.

Polling strategy

• First poll has zero delay — catches already-ready clocks and stripe-mock's instant fixture without waiting 500ms.
• Exponential backoff with full jitter, floored at 500ms. Subsequent sleeps are max(500, :rand.uniform(delay)) where delay starts at 500ms, multiplies by 1.5 each iteration, and caps at 5000ms. Stripe's docs warn about tight-loop rate limits on test clocks; the 500ms floor is non-negotiable.
• Monotonic deadline. The timeout uses System.monotonic_time/1, not system time — NTP adjustments during long test runs do not cause premature timeouts.
• Default timeout: 60 seconds. Override via opts[:timeout] (milliseconds).

Errors

• Timeout — returns {:error, %LatticeStripe.Error{type: :test_clock_timeout, raw_body: %{"clock_id" => _, "last_status" => _, "attempts" => _, "elapsed_ms" => _}}}
• Internal failure — returns {:error, %LatticeStripe.Error{type: :test_clock_failed, raw_body: %{"clock_id" => _, "last_status" => "internal_failure", "attempts" => _}}} — Stripe entered a terminal failure state, retrying will not help.
• HTTP failure during poll — the underlying retrieve/3 error propagates unchanged.

Telemetry

Emits [:lattice_stripe, :test_clock, :advance_and_wait, :start] and [..., :stop] via :telemetry.span/3. Stop metadata includes %{clock_id:, status:, attempts:, outcome: :ok | :error}. Gated by client.telemetry_enabled.

Options

• :timeout — total deadline in ms (default 60_000)
• :initial_interval — first non-zero sleep in ms (default 500, clamped to 500 floor)
• :max_interval — maximum sleep in ms (default 5_000)
• :multiplier — per-iteration growth factor (default 1.5)

Example

{:ok, ready} =
  LatticeStripe.TestHelpers.TestClock.advance_and_wait(
    client,
    clock.id,
    System.system_time(:second) + 86_400 * 30
  )

assert ready.status == :ready

@spec advance_and_wait!(LatticeStripe.Client.t(), String.t(), integer(), keyword()) ::
  t() | no_return()

Bang variant of advance_and_wait/4. Returns %TestClock{} on success, raises LatticeStripe.Error on failure (timeout or internal_failure).

@spec cleanup_tagged(
  LatticeStripe.Client.t(),
  keyword()
) :: {:ok, term()}

Lists and optionally deletes test clocks older than a threshold.

This is the shared deletion core used by both the Owner GenServer's cleanup callback (per-test) and mix lattice_stripe.test_clock.cleanup (backstop). See those callers for the user-facing entry points.

Metadata limitation (A-13g)

Stripe's Test Clock API does not support metadata, so this function cannot filter by a LatticeStripe-specific marker. It filters by age only. This means the Mix task cannot distinguish LatticeStripe-managed clocks from user-created ones. The primary cleanup path (Owner + on_exit) is unaffected.

Options

• :older_than_ms -- only consider clocks older than N milliseconds (default: 3_600_000 = 1 hour)
• :delete -- true to actually delete, false to return candidates only (default: false)
• :name_prefix -- optional string prefix filter on clock name (e.g., "lattice_stripe_test")

Returns

• delete: false -- {:ok, [%TestClock{}, ...]}
• delete: true -- {:ok, %{deleted: n, failed: n, total_matched: n}}

@spec create(LatticeStripe.Client.t(), map(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Creates a new Stripe Test Clock.

Sends POST /v1/test_helpers/test_clocks with the given params and returns the new clock as a typed t().

Parameters

• client — A %LatticeStripe.Client{} struct.
• params — Map of Stripe API params. Required: :frozen_time (integer unix timestamp). Optional: :name (string). Note: :metadata is NOT accepted by the Stripe Test Clock API (see "Metadata support" above).
• opts — Per-request overrides (e.g., :idempotency_key).

Example

{:ok, clock} = LatticeStripe.TestHelpers.TestClock.create(client, %{
  frozen_time: System.system_time(:second),
  name: "renewal-test"
})

@spec delete(LatticeStripe.Client.t(), String.t(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Deletes a Test Clock by id. DELETE /v1/test_helpers/test_clocks/:id.

This cascades: every Customer attached to the clock is deleted, every Subscription canceled. See module docs.

@spec from_map(map()) :: t()

Converts a decoded Stripe API map to a %TestClock{} struct.

Maps all known Stripe test clock fields. Any unrecognized fields are collected into the extra map so no data is silently lost.

Per D-03, the status field is atomized via a whitelist: "ready" → :ready, "advancing" → :advancing, "internal_failure" → :internal_failure. Unknown values pass through as raw strings for forward compatibility with future Stripe enum additions.

@spec list(LatticeStripe.Client.t(), map(), keyword()) ::
  {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}

Lists Test Clocks with optional filters. GET /v1/test_helpers/test_clocks.

@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Retrieves a Test Clock by id. GET /v1/test_helpers/test_clocks/:id.

@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()

Streams Test Clocks lazily via cursor pagination.

Returns a Stream that yields %TestClock{} items. Matches the Phase 12 resource pattern (LatticeStripe.List.stream!/2 + Stream.map).