@gamerdexapp/gamerdex-sync 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,392 @@
+declare const ROOT_FOLDER = "Gamerdex";
+declare const DATA_FILE = "data.json";
+declare const META_FILE = "meta.json";
+/** An app id names a folder, so it is lowercase words joined by single dashes. */
+declare const isAppId: (value: string) => boolean;
+/** The path of the saved data of an app, such as `Gamerdex/whiteout-survival/data.json`. */
+declare const dataPath: (appId: string) => string;
+/** The path of the bookkeeping file of an app, next to its saved data. */
+declare const metaPath: (appId: string) => string;
+
+declare const META_FORMAT = 1;
+interface DeviceRecord {
+    name: string;
+    /** ISO time of the last sync of the device. */
+    lastSeenAt: string;
+}
+/**
+ * The bookkeeping file beside the saved data. It holds no game data and no token. A revision only
+ * counts up, so a device with a wrong clock cannot make old data look new.
+ */
+interface SyncMeta {
+    format: typeof META_FORMAT;
+    appId: string;
+    /** One counter for each chief id. A chief that was removed keeps its counter. */
+    revisions: Record<string, number>;
+    settingsRevision: number;
+    /** Chief ids removed on purpose, with the revision of the removal. */
+    removed: Record<string, number>;
+    devices: Record<string, DeviceRecord>;
+    lastSyncAt: string | null;
+}
+type ParsedMeta = {
+    ok: true;
+    meta: SyncMeta;
+} | {
+    ok: false;
+    error: string;
+};
+declare const emptyMeta: (appId: string) => SyncMeta;
+/** Reads the meta file and checks the whole shape. Nothing is returned for a file that fails. */
+declare const parseMeta: (text: string, appId: string) => ParsedMeta;
+/** Counts one change of a chief. A chief that returns after a removal leaves the removed list. */
+declare const withChiefRevision: (meta: SyncMeta, chiefId: string) => SyncMeta;
+/** Counts the removal of a chief. The counter keeps rising so an old copy cannot return it. */
+declare const withChiefRemoved: (meta: SyncMeta, chiefId: string) => SyncMeta;
+declare const withSettingsRevision: (meta: SyncMeta) => SyncMeta;
+declare const withDevice: (meta: SyncMeta, deviceId: string, device: DeviceRecord) => SyncMeta;
+
+declare const isObject: (value: unknown) => value is Record<string, unknown>;
+/** Deep equality of two JSON values. The order of the keys of an object does not matter. */
+declare const equal: (a: unknown, b: unknown) => boolean;
+
+/**
+ * A step of a path into the saved data. A key of an object, or the id of an entry of a keyed list.
+ */
+type PathStep = string;
+type Path = PathStep[];
+/**
+ * Says how a part of the saved data merges. The app writes one schema for its saved data.
+ *
+ * - `record`: a value that cannot merge. If one side changed it, that side wins. If both changed it,
+ *   it is a conflict.
+ * - `max`: a level. When both sides changed it, the higher one by `order` wins.
+ * - `join`: a list of plain values. The result holds what both lists hold and what either side
+ *   added, and drops what either side removed since the last sync.
+ * - `local`: a value of this device. The merge keeps the local value and ignores the other side.
+ * - `object`: a map of entries. Each entry merges with its own schema. `fields` names the entries
+ *   that differ, `each` covers the others, and an entry with no schema is a `record`. With
+ *   `deleteWins`, a removed entry wins over a change of the other side inside this map.
+ * - `keyed`: a list of objects that each have a string `key`, such as a list of chiefs with an id.
+ *   Its entries merge like the entries of an `object`.
+ */
+type Schema = {
+    type: 'record';
+} | {
+    type: 'max';
+    order: (value: unknown) => number;
+} | {
+    type: 'join';
+} | {
+    type: 'local';
+} | {
+    type: 'object';
+    fields?: Record<string, Schema>;
+    each?: Schema;
+    deleteWins?: boolean;
+} | {
+    type: 'keyed';
+    key: string;
+    item: Schema;
+    deleteWins?: boolean;
+};
+type Side = 'local' | 'remote';
+type ConflictKind = 'both-changed' | 'delete-edit';
+/**
+ * A change that the merge could not settle by itself. The merged data already holds the value of
+ * `taken`, so nothing is lost. The player can pick the other side with `resolveConflict`.
+ */
+interface Conflict {
+    path: Path;
+    kind: ConflictKind;
+    base: unknown;
+    local: unknown;
+    remote: unknown;
+    taken: Side;
+}
+interface MergeInput {
+    /** The data at the last sync. Undefined when this device never synced. */
+    base: unknown;
+    local: unknown;
+    remote: unknown;
+    schema: Schema;
+    /** The side that wins a conflict until the player picks. The default is the remote side. */
+    prefer?: Side;
+}
+interface MergeResult {
+    /** The data for this device. It keeps the values of this device. */
+    merged: unknown;
+    /**
+     * The data for the cloud. It is `merged`, except that a part with the `local` strategy keeps the
+     * value of the cloud, so a value of one device never changes the cloud by itself.
+     */
+    cloud: unknown;
+    conflicts: Conflict[];
+}
+
+/**
+ * Merges the data of this device and the data of the cloud against the data of the last sync.
+ * A part that only one side changed takes that change. A part that both sides changed merges by its
+ * schema, and a part that cannot merge is reported in `conflicts` with the preferred side already
+ * in `merged`.
+ */
+declare const merge: ({ base, local, remote, schema, prefer, }: MergeInput) => MergeResult;
+
+/**
+ * Puts the value of one side of a conflict into the merged data. The player uses this to pick the
+ * side that the merge did not take. A side that holds no value removes the entry.
+ */
+declare const resolveConflict: (merged: unknown, schema: Schema, conflict: Conflict, side: Side) => unknown;
+
+/** Encodes text as base64 from its UTF-8 bytes. It works in the browser and in Node. */
+declare const encodeBase64: (text: string) => string;
+/** Decodes base64 to text. Line breaks in the base64 text are ignored. */
+declare const decodeBase64: (base64: string) => string;
+
+/** A file in the cloud. The version changes with every write and settles which write is newer. */
+interface RemoteFile {
+    content: string;
+    version: string;
+}
+/**
+ * Where the files of an app are kept. A provider reads, writes and removes whole files by path, and
+ * refuses a write that was made from an old version of the file. That refusal is what keeps two
+ * devices from overwriting each other.
+ */
+interface SyncProvider {
+    /** Returns null when the file does not exist. */
+    read(path: string): Promise<RemoteFile | null>;
+    /**
+     * Writes the file. The expected version is the version that was read, or null to create a file
+     * that must not exist yet. Throws `VersionConflictError` when the file changed since.
+     */
+    write(path: string, content: string, expectedVersion: string | null): Promise<{
+        version: string;
+    }>;
+    /** Removes the file. Throws `VersionConflictError` when the file changed since. */
+    remove(path: string, expectedVersion: string): Promise<void>;
+}
+/** The file changed in the cloud after it was read. Read it again and merge. */
+declare class VersionConflictError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+type ProviderErrorKind = 
+/** The token is missing, expired, revoked or has no permission. The player signs in again. */
+'auth'
+/** The provider limits the calls for now. Try again after `retryAfterSeconds`. */
+ | 'rate-limit'
+/** The repository or folder does not exist, or the token cannot see it. */
+ | 'not-found'
+/** The device is offline or the provider cannot be reached. */
+ | 'network'
+/** The provider failed. A later try may work. */
+ | 'server'
+/** The provider answered with something this package does not understand. */
+ | 'invalid';
+declare class ProviderError extends Error {
+    readonly kind: ProviderErrorKind;
+    readonly status?: number | undefined;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(kind: ProviderErrorKind, message: string, status?: number | undefined, retryAfterSeconds?: number | undefined);
+}
+
+interface GitHubOptions {
+    /** The owner and the name of the repository, such as `chiefpansancolt/gamerdex-data`. */
+    repository: string;
+    /** Returns the token. It may refresh the token first, so it is called for every request. */
+    getToken: () => Promise<string>;
+    /** The branch to use. Without it GitHub uses the default branch of the repository. */
+    branch?: string;
+    /** The message of the commit that a write or a removal makes. */
+    commitMessage?: (path: string) => string;
+    fetch?: typeof fetch;
+}
+interface RepositoryCheck {
+    private: boolean;
+    canWrite: boolean;
+    defaultBranch: string;
+}
+/** Keeps the files of an app in a private GitHub repository, through the contents API. */
+declare class GitHubProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    constructor(options: GitHubOptions);
+    read(path: string): Promise<RemoteFile | null>;
+    write(path: string, content: string, expectedVersion: string | null): Promise<{
+        version: string;
+    }>;
+    remove(path: string, expectedVersion: string): Promise<void>;
+    /**
+     * Checks that the repository can be used: it exists, the token can write to it, and it is
+     * private. The saved data of a player must never sit in a public repository.
+     */
+    checkRepository(): Promise<RepositoryCheck>;
+    private contentsUrl;
+    private message;
+    private request;
+    private assertOk;
+    private invalid;
+}
+
+/**
+ * A provider that keeps the files in memory. It follows the same version rules as a real provider,
+ * so the sync flow of an app can be tested without a network.
+ */
+declare class MemoryProvider implements SyncProvider {
+    private files;
+    private counter;
+    read(path: string): Promise<RemoteFile | null>;
+    write(path: string, content: string, expectedVersion: string | null): Promise<{
+        version: string;
+    }>;
+    remove(path: string, expectedVersion: string): Promise<void>;
+    /** The paths of the files that exist, in the order they were first written. */
+    paths(): string[];
+}
+
+/**
+ * What this device remembers about the last sync. The app keeps it in the browser, next to the
+ * saved data but outside it, and passes it back on the next sync.
+ */
+interface SyncState {
+    /** The cloud data as this device last saw it. */
+    base: unknown;
+    dataVersion: string | null;
+    metaVersion: string | null;
+}
+/** What to do when this device never synced and both the device and the cloud hold data. */
+type FirstSyncChoice = 'merge' | 'keep-local' | 'keep-cloud';
+interface SyncOptions {
+    appId: string;
+    deviceId: string;
+    deviceName: string;
+    provider: SyncProvider;
+    schema: Schema;
+    /** The data of this device. */
+    local: unknown;
+    /** The state kept after the last sync, or null when this device never synced. */
+    state: SyncState | null;
+    firstSync?: FirstSyncChoice;
+    /** Returns true when the data is whole and safe to store. Called before any write. */
+    validate?: (data: unknown) => boolean;
+    /** Lets the app change the revisions of the meta file for this sync. */
+    updateMeta?: (meta: SyncMeta) => SyncMeta;
+    /** The current time as an ISO text. */
+    now: () => string;
+}
+type SyncResult = {
+    status: 'synced';
+    /** The data to store on this device. */
+    data: unknown;
+    /** The state to keep for the next sync. */
+    state: SyncState;
+    conflicts: Conflict[];
+    /** True when the cloud changed during this sync. */
+    uploaded: boolean;
+} | {
+    /** The device and the cloud both hold data and the app has not said what to do. */
+    status: 'needs-choice';
+    local: unknown;
+    remote: unknown;
+};
+/** The data in the cloud is not whole, so nothing was written. */
+declare class RemoteDataError extends Error {
+    constructor(message: string);
+}
+/** Other devices kept writing during every try, so the sync stopped. Try again later. */
+declare class SyncBusyError extends Error {
+    constructor();
+}
+/**
+ * Brings this device and the cloud to the same data. It reads the cloud, merges the three copies,
+ * writes the cloud copy when it changed, and returns the data to store on this device with the
+ * state to keep. It never changes the device by itself, and it does not write when the cloud data
+ * or the merged data fail `validate`.
+ *
+ * Throws `ProviderError` when the provider fails, `RemoteDataError` when the cloud data is not
+ * whole, and `SyncBusyError` when other devices keep writing.
+ */
+declare const sync: (options: SyncOptions) => Promise<SyncResult>;
+
+/**
+ * Returns the merged data as it must be stored in the cloud: every part with the `local` strategy
+ * keeps the value that the cloud already holds, so a value of one device never changes the cloud.
+ */
+declare const restoreCloudValues: (merged: unknown, remote: unknown, schema: Schema) => unknown;
+
+/** The public values of the Gamerdex Sync GitHub App. The client secret is never kept here. */
+declare const GITHUB_APP: {
+    readonly slug: "gamerdex-sync";
+    readonly clientId: "Iv23liwzjj3x8O2K5ALA";
+};
+
+/** The tokens of a signed in player. Times are milliseconds since 1970. */
+interface StoredTokens {
+    accessToken: string;
+    accessExpiresAt: number;
+    refreshToken: string;
+    refreshExpiresAt: number;
+}
+/** The answer of the token function, with lifetimes in seconds. */
+interface TokenResponse {
+    accessToken: string;
+    expiresIn: number;
+    refreshToken: string;
+    refreshExpiresIn: number;
+}
+declare const parseTokenResponse: (body: unknown) => TokenResponse | null;
+declare const toStoredTokens: (response: TokenResponse, nowMs: number) => StoredTokens;
+
+interface TokenSourceOptions {
+    /** The address of the token function, without a trailing slash. */
+    endpoint: string;
+    /** Reads the tokens that this device saved, or null when the player is signed out. */
+    load: () => StoredTokens | null;
+    /** Saves the tokens, or removes them when null. */
+    save: (tokens: StoredTokens | null) => void;
+    now: () => number;
+    fetch?: typeof fetch;
+}
+/**
+ * Keeps a player signed in. `getToken` returns a token that is valid for at least a minute and
+ * renews it first when needed. It is meant to be the `getToken` of `GitHubProvider`.
+ */
+declare const createTokenSource: (options: TokenSourceOptions) => {
+    /** Finishes a sign in with the code from the callback page. */
+    signIn: (code: string, redirectUri: string) => Promise<StoredTokens>;
+    signOut: () => void;
+    isSignedIn: () => boolean;
+    getToken: () => Promise<string>;
+};
+
+/** A random value that ties a sign-in answer to the sign-in that this device started. */
+declare const newState: () => string;
+declare const authorizeUrl: (redirectUri: string, state: string) => string;
+/** The page where the player picks the repository that the app may use. */
+declare const installUrl: (state: string) => string;
+type CallbackResult = {
+    ok: true;
+    code: string;
+} | {
+    ok: false;
+    reason: 'denied' | 'state' | 'missing';
+};
+/**
+ * Reads the query of the sign-in callback page. The state must equal the state that was saved when
+ * the sign-in started, or the answer is refused.
+ */
+declare const readCallback: (search: string, expectedState: string | null) => CallbackResult;
+
+interface InstalledRepository {
+    /** The owner and the name, such as `chiefpansancolt/gamerdex-data`. */
+    fullName: string;
+    private: boolean;
+}
+/**
+ * Lists the repositories that the player gave to the GitHub App, for the first 100 installations
+ * and the first 100 repositories of each. The player picks the repository for the synced data.
+ */
+declare const listInstalledRepositories: (token: string, send?: typeof fetch) => Promise<InstalledRepository[]>;
+
+export { type CallbackResult, type Conflict, type ConflictKind, DATA_FILE, type DeviceRecord, type FirstSyncChoice, GITHUB_APP, type GitHubOptions, GitHubProvider, type InstalledRepository, META_FILE, META_FORMAT, MemoryProvider, type MergeInput, type MergeResult, type ParsedMeta, type Path, type PathStep, ProviderError, type ProviderErrorKind, ROOT_FOLDER, RemoteDataError, type RemoteFile, type RepositoryCheck, type Schema, type Side, type StoredTokens, SyncBusyError, type SyncMeta, type SyncOptions, type SyncProvider, type SyncResult, type SyncState, type TokenResponse, type TokenSourceOptions, VersionConflictError, authorizeUrl, createTokenSource, dataPath, decodeBase64, emptyMeta, encodeBase64, equal, installUrl, isAppId, isObject, listInstalledRepositories, merge, metaPath, newState, parseMeta, parseTokenResponse, readCallback, resolveConflict, restoreCloudValues, sync, toStoredTokens, withChiefRemoved, withChiefRevision, withDevice, withSettingsRevision };