@relayfile/sdk 0.10.61 → 0.10.62

package/dist/client.d.ts

@@ -12,7 +12,15 @@ export type AccessTokenProvider = string | (() => string | Promise<string>);
  * `RELAYFILE_REFRESH_TOKEN`). Pass this as `token` and the client auto-wraps it
  * in the correct rotating provider — a RelayAuth `relay_pa` pair refreshes at
  * RelayAuth, a Cloud device-auth pair at Cloud — so the short access token is
- * rotated automatically with no extra wiring.
+ * rotated automatically.
+ *
+ * Rotation is in-memory: on refresh the refresh token rotates too and the old
+ * one is revoked, so the pair you passed here (e.g. the one in your `.env`) is
+ * spent after the first refresh. In a long-lived process this is invisible, but
+ * a process that restarts (a redeploy, a new worker) will reload the original,
+ * now-revoked pair and fail with `invalid_grant` / "refresh token revoked".
+ * Supply {@link RelayFileClientOptions.onTokens} to persist each rotated pair so
+ * the next process boots from a live credential.
  */
 export interface RelayFileTokenPair {
     accessToken: string;
@@ -25,6 +33,15 @@ export interface RelayFileTokenPair {
     /** Cloud API URL for a Cloud device-auth pair. */
     apiUrl?: string;
 }
+/**
+ * Called after the client rotates the access+refresh {@link RelayFileTokenPair}.
+ * Persist the new pair (e.g. write it back to your secret store / `.env`) so a
+ * later process starts from a live credential instead of the revoked original.
+ * The callback is best-effort and retried on the next request until it succeeds;
+ * a throw is swallowed (the in-memory access token stays usable) but leaves the
+ * pair unpersisted, so make it durable.
+ */
+export type RelayFileTokenPersister = (tokens: RelayFileTokenPair) => void | Promise<void>;
 export interface RelayFileRetryOptions {
     maxRetries?: number;
     baseDelayMs?: number;
@@ -58,6 +75,15 @@ export interface RelayFileClientOptions {
      * and `aud` containing `relayfile`.
      */
     token: AccessTokenProvider | RelayFileTokenPair;
+    /**
+     * Persistence hook for a rotating {@link RelayFileTokenPair}. Called with the
+     * new pair each time the access token is refreshed (the refresh token rotates
+     * too). Write it back to your secret store so a process that restarts reloads a
+     * live credential instead of the spent original — without this, a `token` pair
+     * survives only within one process lifetime. Ignored when `token` is a string
+     * or token factory (that provider owns its own rotation).
+     */
+    onTokens?: RelayFileTokenPersister;
     fetchImpl?: typeof fetch;
     userAgent?: string;
     retry?: RelayFileRetryOptions;

package/dist/client.js

@@ -4,8 +4,9 @@ import { createRelayauthPathTokenAccessTokenProvider, isRelayauthRefreshToken }
 import { InvalidStateError, MergeConflictError, ParentMovedError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 // Resolve the `token` option into a concrete AccessTokenProvider. A string or
 // function is used as-is; a token PAIR is auto-wrapped in the rotating provider
-// that matches the refresh token's issuer.
-function resolveTokenOption(token) {
+// that matches the refresh token's issuer. When `onTokens` is supplied, each
+// rotated pair is handed back so the caller can persist it across restarts.
+function resolveTokenOption(token, onTokens) {
     if (typeof token === "string" || typeof token === "function") {
         return token;
     }
@@ -16,7 +17,17 @@ function resolveTokenOption(token) {
             accessTokenExpiresAt: token.accessTokenExpiresAt,
             refreshTokenExpiresAt: token.refreshTokenExpiresAt,
             relayauthUrl: token.relayauthUrl
-        });
+        }, onTokens
+            ? {
+                onTokens: (rotated) => onTokens({
+                    accessToken: rotated.accessToken,
+                    refreshToken: rotated.refreshToken,
+                    accessTokenExpiresAt: rotated.accessTokenExpiresAt,
+                    refreshTokenExpiresAt: rotated.refreshTokenExpiresAt,
+                    relayauthUrl: rotated.relayauthUrl
+                })
+            }
+            : undefined);
     }
     return createRelayfileCloudAccessTokenProvider({
         apiUrl: token.apiUrl,
@@ -25,7 +36,17 @@ function resolveTokenOption(token) {
         // The cloud provider treats an unparseable expiry as "refresh now".
         accessTokenExpiresAt: token.accessTokenExpiresAt ?? "",
         refreshTokenExpiresAt: token.refreshTokenExpiresAt
-    });
+    }, onTokens
+        ? {
+            onTokens: (rotated) => onTokens({
+                accessToken: rotated.accessToken,
+                refreshToken: rotated.refreshToken,
+                accessTokenExpiresAt: rotated.accessTokenExpiresAt,
+                refreshTokenExpiresAt: rotated.refreshTokenExpiresAt,
+                apiUrl: rotated.apiUrl
+            })
+        }
+        : undefined);
 }
 /** Default base URL for the hosted Relayfile API */
 export const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
@@ -1249,7 +1270,7 @@ export class RelayFileClient {
     retryOptions;
     constructor(options) {
         this.baseUrl = (options.baseUrl ?? DEFAULT_RELAYFILE_BASE_URL).replace(/\/+$/, "");
-        this.tokenProvider = resolveTokenOption(options.token);
+        this.tokenProvider = resolveTokenOption(options.token, options.onTokens);
         this.fetchImpl = options.fetchImpl ?? fetch.bind(globalThis);
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);

package/dist/cloud-token-provider.js

@@ -14,6 +14,11 @@ export function createRelayfileCloudAccessTokenProvider(initialTokens, options =
         apiUrl: normalizeNonEmptyString(initialTokens.apiUrl) ?? cloudApiUrl
     };
     let refreshPromise;
+    // A rotated token set whose `onTokens` persistence callback has not yet
+    // succeeded. Until it does, a consumed refresh token may still live in the
+    // caller's persisted copy (→ `invalid_grant` after restart), so we retry the
+    // callback on every subsequent use rather than treating rotation as complete.
+    let pendingPersist;
     return async () => {
         if (shouldRefresh(tokens, refreshWindowMs)) {
             if (!refreshPromise) {
@@ -26,6 +31,10 @@ export function createRelayfileCloudAccessTokenProvider(initialTokens, options =
                 refreshPromise = undefined;
             }
         }
+        else if (pendingPersist) {
+            // No refresh needed, but a prior rotation still owes a successful persist.
+            await persistPendingTokens();
+        }
         return tokens.accessToken;
     };
     async function refresh() {
@@ -42,7 +51,32 @@ export function createRelayfileCloudAccessTokenProvider(initialTokens, options =
             throw new CloudApiError(response.status, payload);
         }
         tokens = readTokenSetFromPayload(payload, cloudApiUrl);
-        await options.onTokens?.({ ...tokens });
+        pendingPersist = { ...tokens };
+        await persistPendingTokens();
+    }
+    // Best-effort, retried persistence. A callback failure never rejects the
+    // provider — the in-memory access token is valid and usable — but the set
+    // stays pending so the next provider() call re-attempts, so a durable copy
+    // eventually catches up with the rotated refresh token.
+    async function persistPendingTokens() {
+        if (!pendingPersist) {
+            return;
+        }
+        if (!options.onTokens) {
+            pendingPersist = undefined;
+            return;
+        }
+        const toPersist = pendingPersist;
+        try {
+            await options.onTokens({ ...toPersist });
+            // Only clear if nothing rotated again while the callback was in flight.
+            if (pendingPersist === toPersist) {
+                pendingPersist = undefined;
+            }
+        }
+        catch {
+            // Keep pending; retried on the next use.
+        }
     }
 }
 function shouldRefresh(tokens, refreshWindowMs) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileTokenPair, type RelayFileChangeLogOptions, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileTokenPair, type RelayFileTokenPersister, type RelayFileChangeLogOptions, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
 export type { RelayFileReadCacheOptions } from "./types.js";
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const RELAYFILE_VERSION = "0.10.61";
+export declare const RELAYFILE_VERSION = "0.10.62";

package/dist/package-version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/sync-package-version.mjs during every SDK build.
-export const RELAYFILE_VERSION = "0.10.61";
+export const RELAYFILE_VERSION = "0.10.62";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.10.61",
+  "version": "0.10.62",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -60,15 +60,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.10.61",
+    "@relayfile/core": "0.10.62",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.10.61",
-    "@relayfile/mount-darwin-x64": "0.10.61",
-    "@relayfile/mount-linux-arm64": "0.10.61",
-    "@relayfile/mount-linux-x64": "0.10.61"
+    "@relayfile/mount-darwin-arm64": "0.10.62",
+    "@relayfile/mount-darwin-x64": "0.10.62",
+    "@relayfile/mount-linux-arm64": "0.10.62",
+    "@relayfile/mount-linux-x64": "0.10.62"
   },
   "devDependencies": {
     "typescript": "^5.7.3",