@spec create(ArchAstro.Client.t(), ArchAstro.Types.Operations.PostApiV1Kv.Input.t()) ::
  {:ok, ArchAstro.Types.KeyValueStorageEntry.t()}
  | {:error, ArchAstro.Error.reason()}

Create a key-value storage entry

Creates a new key-value storage entry for the target user under the given key. The key must not already exist for this user; use the upsert endpoint to create or overwrite in a single call.

End-user (user-JWT) callers always write to their own storage. Developer and server-to-server callers must supply a user param identifying the target user within their app's scope. Attempting to write for a user in a different app returns 404.

The newly created key-value storage entry.

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

Delete a key-value storage entry

Permanently deletes the key-value storage entry identified by key for the target user. Returns 204 No Content on success and 404 if the entry does not exist.

End-user (user-JWT) callers can only delete entries they own. Developer and server-to-server callers must supply a user param identifying the target user within their app's scope.

Empty response body. HTTP 204 No Content on success.

@spec get(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1KvKey.Params.t()
) ::
  {:ok, ArchAstro.Types.KeyValueStorageEntry.t()}
  | {:error, ArchAstro.Error.reason()}

Retrieve a key-value storage entry

Returns the key-value storage entry identified by key for the target user. Returns 404 if no entry exists for that key.

End-user (user-JWT) callers retrieve entries from their own storage. Developer and server-to-server callers must supply a user param identifying the target user within their app's scope.

The key-value storage entry for the given key.

@spec list(ArchAstro.Client.t(), ArchAstro.Types.Operations.GetApiV1Kv.Params.t()) ::
  {:ok, ArchAstro.Types.KeyValueStorageEntryPage.t()}
  | {:error, ArchAstro.Error.reason()}

List key-value storage entries

Returns key-value storage entries in one of two modes depending on the caller's auth scope.

User-JWT callers receive a flat list of all their own entries with no pagination fields. The page, page_size, user, user_search, and key params are ignored.

Developer and server-to-server callers receive a page-based paginated response across all users within the caller's app. Use user to scope results to a single user, user_search to do a substring match on email or full name, and key to filter entries whose key starts with the given prefix. Results are ordered by creation time descending.

Key-value storage entries for the current page, with pagination metadata for developer and server-to-server callers.

@spec upsert(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PutApiV1KvKey.Input.t()
) ::
  {:ok, ArchAstro.Types.KeyValueStorageEntry.t()}
  | {:error, ArchAstro.Error.reason()}

Create or update a key-value storage entry

Creates a new key-value storage entry for the given key, or overwrites the value if an entry already exists. This is the idempotent alternative to the create endpoint: safe to call regardless of whether the key already exists.

End-user (user-JWT) callers always write to their own storage. Developer and server-to-server callers must supply a user param identifying the target user within their app's scope. Attempting to write for a user in a different app returns 404.

The created or updated key-value storage entry.