/* * Copyright 2026 macuguita * * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by * the European Commission - subsequent versions of the EUPL (the "Licence"); * You may not use this work except in compliance with the Licence. * You may obtain a copy of the Licence at: * * https://joinup.ec.europa.eu/software/page/eupl * * Unless required by applicable law or agreed to in writing, software * distributed under the Licence is distributed on an "AS IS" basis, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the Licence for the specific language governing permissions and * limitations under the Licence. */ package com.macuguita.lib.api.persista; import java.time.Duration; import java.util.UUID; import java.util.concurrent.CompletableFuture; import net.minecraft.resources.Identifier; import com.mojang.serialization.Codec; import com.macuguita.lib.impl.persista.PersistaAPIImpl; /** * Entry point for registering and interacting with Persista data tokens. * *

Overview

* Persista provides cached, network-backed persistent player data. * Data may be fetched from or written to a remote HTTP API depending on cache state. * *

Important behavior guarantees

* * *

Rate limiting & server behavior

* * *

Usage guidelines

* */ public final class PersistaAPI { public static final String API_URL = "https://persista.macuguita.com/api"; public static final Duration CACHE_DURATION = Duration.ofHours(1); private PersistaAPI() {} /** * Registers a new data token for the given identifier and codec. * *

This should be called during mod initialization only.

* * @param id unique identifier for the data type * @param codec serialization codec for the data type * @param type of stored data * @return a DataToken representing the registered data */ public static DataToken register(Identifier id, Codec codec) { return PersistaAPIImpl.register(id, codec); } /** * Forces a refresh of all registered data for the given player. * *

This will trigger multiple network requests in parallel or sequence * depending on internal implementation.

* *

Callers should avoid invoking this frequently as it may cause * significant network load.

* * @param playerId target player UUID * @return future that completes when all refresh operations finish */ public static CompletableFuture refreshAll(UUID playerId) { return PersistaAPIImpl.refreshAll(playerId); } }