@gamerdexapp/gamerdex-sync 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-18
+
+### Added
+
+- `DropboxProvider` keeps the files in the app folder of the Dropbox of the player. It writes with
+  the revision that was read and fails with a version conflict when the file changed since.
+- `OneDriveProvider` keeps the files in the app folder of the OneDrive of a personal Microsoft
+  account. It writes with the `eTag` that was read and creates a new file only when none exists.
+- `dropboxAuthorizeUrl()` with `DROPBOX_SCOPES`, and `microsoftAuthorizeUrl()` with
+  `ONEDRIVE_FILE_SCOPE` and `ONEDRIVE_SCOPES`, for the two sign in pages.
+- `ProviderError.detail` also reads the summary of a failed Dropbox request.
+
+## [0.2.1] - 2026-10-18
+
+### Fixed
+
+- `GoogleDriveProvider` no longer fails when the Drive search does not list a file or folder that it
+  has just created. Drive can lag behind a create, so the provider now counts the new item with the
+  creation time that Drive returns.
+
 ## [0.2.0] - 2026-10-17
 
 ### Added

package/README.md

@@ -28,7 +28,7 @@ const result = await sync({
   appId: "my-app",
   deviceId: "device-1",
   deviceName: "Laptop",
-  provider: new MemoryProvider(), // GitHubProvider in an app
+  provider: new MemoryProvider(), // GitHubProvider, GoogleDriveProvider, DropboxProvider or OneDriveProvider in an app
   schema,
   local: { chief: { level: 5 } },
   state: null, // the state that the last sync returned, or null on the first sync

package/dist/index.d.mts

@@ -429,6 +429,7 @@ declare class GoogleDriveProvider implements SyncProvider {
     private upload;
     private createFile;
     private deleteItem;
+    private itemOf;
     private stringField;
     private request;
     private failure;
@@ -442,4 +443,84 @@ declare const GOOGLE_DRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
  */
 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 };
+interface DropboxOptions {
+    /** 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 Dropbox of the player. The app should have the App folder
+ * access type with the `files.content.read` and `files.content.write` scopes, so it sees only its
+ * own folder under `Apps`.
+ *
+ * Dropbox writes with an expected revision. An upload in `update` mode with `strict_conflict`
+ * fails when the file changed since, and an upload in `add` mode fails when the file exists.
+ */
+declare class DropboxProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    constructor(options: DropboxOptions);
+    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 request;
+    /**
+     * Reads a failed answer. Dropbox reports a failure that belongs to the call, such as a missing
+     * file or a conflict, with status 409. The caller decides what that means. Every other status
+     * is a failure of the request and is thrown here.
+     */
+    private failure;
+    private unexpected;
+    private invalid;
+}
+
+interface OneDriveOptions {
+    /** 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 OneDrive of the player, in the app folder under `Apps`. It
+ * needs only the `Files.ReadWrite.AppFolder` scope, so it sees no other file. The app folder
+ * exists for personal Microsoft accounts.
+ *
+ * A write sends the `eTag` that was read in an `If-Match` header, and a new file is created with
+ * `conflictBehavior=fail`. OneDrive answers 412 and 409 when the file changed or exists.
+ */
+declare class OneDriveProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    constructor(options: OneDriveOptions);
+    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 itemUrl;
+    private ifMatch;
+    private info;
+    /** The download address is signed, so it must not carry the token. */
+    private fetchContent;
+    private request;
+    private assertOk;
+    private invalid;
+}
+
+/** The scopes that sync asks for. Together with the App folder access type, they reach one folder. */
+declare const DROPBOX_SCOPES: readonly ["files.content.read", "files.content.write"];
+/**
+ * The address of the Dropbox sign in page. `token_access_type=offline` makes Dropbox send a
+ * refresh token, which does not expire until the player removes the access.
+ */
+declare const dropboxAuthorizeUrl: (clientId: string, redirectUri: string, state: string) => string;
+
+/** The file scope that sync asks for. It reaches only the app folder of the player. */
+declare const ONEDRIVE_FILE_SCOPE = "Files.ReadWrite.AppFolder";
+/** The file scope, and `offline_access`, which makes Microsoft send a refresh token. */
+declare const ONEDRIVE_SCOPES: readonly ["Files.ReadWrite.AppFolder", "offline_access"];
+/** The address of the Microsoft sign in page for personal accounts. */
+declare const microsoftAuthorizeUrl: (clientId: string, redirectUri: string, state: string) => string;
+
+export { type CallbackResult, type Conflict, type ConflictKind, DATA_FILE, DROPBOX_SCOPES, type DeviceRecord, type DropboxOptions, DropboxProvider, type FirstSyncChoice, GITHUB_APP, GOOGLE_DRIVE_SCOPE, type GitHubOptions, GitHubProvider, type GoogleDriveOptions, GoogleDriveProvider, type InstalledRepository, META_FILE, META_FORMAT, MemoryProvider, type MergeInput, type MergeResult, ONEDRIVE_FILE_SCOPE, ONEDRIVE_SCOPES, type OneDriveOptions, OneDriveProvider, 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, dropboxAuthorizeUrl, emptyMeta, encodeBase64, equal, googleAuthorizeUrl, installUrl, isAppId, isObject, listInstalledRepositories, merge, metaPath, microsoftAuthorizeUrl, newState, parseMeta, parseTokenResponse, readCallback, resolveConflict, restoreCloudValues, sync, toStoredTokens, withChiefRemoved, withChiefRevision, withDevice, withSettingsRevision };

package/dist/index.d.ts

@@ -429,6 +429,7 @@ declare class GoogleDriveProvider implements SyncProvider {
     private upload;
     private createFile;
     private deleteItem;
+    private itemOf;
     private stringField;
     private request;
     private failure;
@@ -442,4 +443,84 @@ declare const GOOGLE_DRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
  */
 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 };
+interface DropboxOptions {
+    /** 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 Dropbox of the player. The app should have the App folder
+ * access type with the `files.content.read` and `files.content.write` scopes, so it sees only its
+ * own folder under `Apps`.
+ *
+ * Dropbox writes with an expected revision. An upload in `update` mode with `strict_conflict`
+ * fails when the file changed since, and an upload in `add` mode fails when the file exists.
+ */
+declare class DropboxProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    constructor(options: DropboxOptions);
+    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 request;
+    /**
+     * Reads a failed answer. Dropbox reports a failure that belongs to the call, such as a missing
+     * file or a conflict, with status 409. The caller decides what that means. Every other status
+     * is a failure of the request and is thrown here.
+     */
+    private failure;
+    private unexpected;
+    private invalid;
+}
+
+interface OneDriveOptions {
+    /** 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 OneDrive of the player, in the app folder under `Apps`. It
+ * needs only the `Files.ReadWrite.AppFolder` scope, so it sees no other file. The app folder
+ * exists for personal Microsoft accounts.
+ *
+ * A write sends the `eTag` that was read in an `If-Match` header, and a new file is created with
+ * `conflictBehavior=fail`. OneDrive answers 412 and 409 when the file changed or exists.
+ */
+declare class OneDriveProvider implements SyncProvider {
+    private readonly options;
+    private readonly send;
+    constructor(options: OneDriveOptions);
+    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 itemUrl;
+    private ifMatch;
+    private info;
+    /** The download address is signed, so it must not carry the token. */
+    private fetchContent;
+    private request;
+    private assertOk;
+    private invalid;
+}
+
+/** The scopes that sync asks for. Together with the App folder access type, they reach one folder. */
+declare const DROPBOX_SCOPES: readonly ["files.content.read", "files.content.write"];
+/**
+ * The address of the Dropbox sign in page. `token_access_type=offline` makes Dropbox send a
+ * refresh token, which does not expire until the player removes the access.
+ */
+declare const dropboxAuthorizeUrl: (clientId: string, redirectUri: string, state: string) => string;
+
+/** The file scope that sync asks for. It reaches only the app folder of the player. */
+declare const ONEDRIVE_FILE_SCOPE = "Files.ReadWrite.AppFolder";
+/** The file scope, and `offline_access`, which makes Microsoft send a refresh token. */
+declare const ONEDRIVE_SCOPES: readonly ["Files.ReadWrite.AppFolder", "offline_access"];
+/** The address of the Microsoft sign in page for personal accounts. */
+declare const microsoftAuthorizeUrl: (clientId: string, redirectUri: string, state: string) => string;
+
+export { type CallbackResult, type Conflict, type ConflictKind, DATA_FILE, DROPBOX_SCOPES, type DeviceRecord, type DropboxOptions, DropboxProvider, type FirstSyncChoice, GITHUB_APP, GOOGLE_DRIVE_SCOPE, type GitHubOptions, GitHubProvider, type GoogleDriveOptions, GoogleDriveProvider, type InstalledRepository, META_FILE, META_FORMAT, MemoryProvider, type MergeInput, type MergeResult, ONEDRIVE_FILE_SCOPE, ONEDRIVE_SCOPES, type OneDriveOptions, OneDriveProvider, 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, dropboxAuthorizeUrl, emptyMeta, encodeBase64, equal, googleAuthorizeUrl, installUrl, isAppId, isObject, listInstalledRepositories, merge, metaPath, microsoftAuthorizeUrl, newState, parseMeta, parseTokenResponse, readCallback, resolveConflict, restoreCloudValues, sync, toStoredTokens, withChiefRemoved, withChiefRevision, withDevice, withSettingsRevision };