@gamerdexapp/gamerdex-sync 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-17
+
+### Added
+
+- `GoogleDriveProvider` keeps the files in the Google Drive of the player, in a visible `Gamerdex`
+  folder, with the narrow `drive.file` scope. Drive cannot refuse a write made from an old version,
+  so the provider checks the head revision before the upload and the revision list after it. When
+  another device wrote in between, its content is put back and the sync merges both sides.
+- `googleAuthorizeUrl()` and `GOOGLE_DRIVE_SCOPE` for the Google sign in page.
+- `ProviderError.detail` also reads the message of a failed Google request.
+
+## [0.1.1] - 2026-10-17
+
+### Added
+
+- `ProviderError.detail` carries the message that GitHub sends with a failed request, such as
+  "Resource not accessible by integration", so an app can log the reason of a failure.
+
+### Changed
+
+- A sync that changes nothing no longer writes the meta file, so the repository gets no empty
+  commits. The meta file is still written when data is uploaded, when a device syncs for the first
+  time, and when the app changes the revisions.
+
 ## [0.1.0] - 2026-10-17
 
 First release.

package/dist/index.d.mts

@@ -188,7 +188,11 @@ 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);
+    /** The message that the provider sent with the failed request, when it sent one. */
+    readonly detail?: string | undefined;
+    constructor(kind: ProviderErrorKind, message: string, status?: number | undefined, retryAfterSeconds?: number | undefined, 
+    /** The message that the provider sent with the failed request, when it sent one. */
+    detail?: string | undefined);
 }
 
 interface GitHubOptions {
@@ -389,4 +393,53 @@ interface InstalledRepository {
  */
 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 };
+interface GoogleDriveOptions {
+    /** Returns the token. It may refresh the token first, so it is called for every request. */
+    getToken: () => Promise<string>;
+    fetch?: typeof fetch;
+}
+/**
+ * Keeps the files of an app in the Google Drive of the player, in a visible `Gamerdex` folder. It
+ * needs only the `drive.file` scope, which sees the files that this app created.
+ *
+ * Drive cannot refuse a write made from an old version. Writes are checked in two steps instead:
+ * the head revision must equal the expected version before the upload, and the revision list must
+ * show the new revision directly on top of the expected one after it. When another device wrote in
+ * between, its content is written back as the head and `VersionConflictError` is thrown, so the
+ * next sync merges both sides.
+ */
+declare class GoogleDriveProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    private readonly folders;
+    constructor(options: GoogleDriveOptions);
+    read(path: string): Promise<RemoteFile | null>;
+    write(path: string, content: string, expectedVersion: string | null): Promise<{
+        version: string;
+    }>;
+    remove(path: string, expectedVersion: string): Promise<void>;
+    private create;
+    private findFile;
+    private locate;
+    private folderId;
+    private children;
+    private headOf;
+    private revisionContent;
+    private revisionBefore;
+    private upload;
+    private createFile;
+    private deleteItem;
+    private stringField;
+    private request;
+    private failure;
+}
+
+/** The only Drive scope that sync asks for. It sees the files that the app created itself. */
+declare const GOOGLE_DRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
+/**
+ * The address of the Google sign in page. `access_type=offline` and `prompt=consent` make Google
+ * send a refresh token, which it otherwise sends only the first time the player agrees.
+ */
+declare const googleAuthorizeUrl: (clientId: string, redirectUri: string, state: string) => string;
+
+export { type CallbackResult, type Conflict, type ConflictKind, DATA_FILE, type DeviceRecord, type FirstSyncChoice, GITHUB_APP, GOOGLE_DRIVE_SCOPE, type GitHubOptions, GitHubProvider, type GoogleDriveOptions, GoogleDriveProvider, 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, googleAuthorizeUrl, installUrl, isAppId, isObject, listInstalledRepositories, merge, metaPath, newState, parseMeta, parseTokenResponse, readCallback, resolveConflict, restoreCloudValues, sync, toStoredTokens, withChiefRemoved, withChiefRevision, withDevice, withSettingsRevision };

package/dist/index.d.ts

@@ -188,7 +188,11 @@ 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);
+    /** The message that the provider sent with the failed request, when it sent one. */
+    readonly detail?: string | undefined;
+    constructor(kind: ProviderErrorKind, message: string, status?: number | undefined, retryAfterSeconds?: number | undefined, 
+    /** The message that the provider sent with the failed request, when it sent one. */
+    detail?: string | undefined);
 }
 
 interface GitHubOptions {
@@ -389,4 +393,53 @@ interface InstalledRepository {
  */
 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 };
+interface GoogleDriveOptions {
+    /** Returns the token. It may refresh the token first, so it is called for every request. */
+    getToken: () => Promise<string>;
+    fetch?: typeof fetch;
+}
+/**
+ * Keeps the files of an app in the Google Drive of the player, in a visible `Gamerdex` folder. It
+ * needs only the `drive.file` scope, which sees the files that this app created.
+ *
+ * Drive cannot refuse a write made from an old version. Writes are checked in two steps instead:
+ * the head revision must equal the expected version before the upload, and the revision list must
+ * show the new revision directly on top of the expected one after it. When another device wrote in
+ * between, its content is written back as the head and `VersionConflictError` is thrown, so the
+ * next sync merges both sides.
+ */
+declare class GoogleDriveProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    private readonly folders;
+    constructor(options: GoogleDriveOptions);
+    read(path: string): Promise<RemoteFile | null>;
+    write(path: string, content: string, expectedVersion: string | null): Promise<{
+        version: string;
+    }>;
+    remove(path: string, expectedVersion: string): Promise<void>;
+    private create;
+    private findFile;
+    private locate;
+    private folderId;
+    private children;
+    private headOf;
+    private revisionContent;
+    private revisionBefore;
+    private upload;
+    private createFile;
+    private deleteItem;
+    private stringField;
+    private request;
+    private failure;
+}
+
+/** The only Drive scope that sync asks for. It sees the files that the app created itself. */
+declare const GOOGLE_DRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
+/**
+ * The address of the Google sign in page. `access_type=offline` and `prompt=consent` make Google
+ * send a refresh token, which it otherwise sends only the first time the player agrees.
+ */
+declare const googleAuthorizeUrl: (clientId: string, redirectUri: string, state: string) => string;
+
+export { type CallbackResult, type Conflict, type ConflictKind, DATA_FILE, type DeviceRecord, type FirstSyncChoice, GITHUB_APP, GOOGLE_DRIVE_SCOPE, type GitHubOptions, GitHubProvider, type GoogleDriveOptions, GoogleDriveProvider, 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, googleAuthorizeUrl, installUrl, isAppId, isObject, listInstalledRepositories, merge, metaPath, newState, parseMeta, parseTokenResponse, readCallback, resolveConflict, restoreCloudValues, sync, toStoredTokens, withChiefRemoved, withChiefRevision, withDevice, withSettingsRevision };