@cubee_ee/sdk 0.2.3 → 0.2.5

package/dist/idl/index.d.ts

@@ -98,6 +98,91 @@ export declare const CUBIC_POOL_IDL: {
             name: string;
             type: string;
         })[];
+    } | {
+        name: string;
+        docs: string[];
+        discriminator: number[];
+        accounts: ({
+            name: string;
+            docs: string[];
+            writable: boolean;
+            signer?: undefined;
+        } | {
+            name: string;
+            docs: string[];
+            writable?: undefined;
+            signer?: undefined;
+        } | {
+            name: string;
+            docs: string[];
+            signer: boolean;
+            writable?: undefined;
+        } | {
+            name: string;
+            docs: string[];
+            writable: boolean;
+            signer: boolean;
+        } | {
+            name: string;
+            docs?: undefined;
+            writable?: undefined;
+            signer?: undefined;
+        })[];
+        args: {
+            name: string;
+            type: string;
+        }[];
+    } | {
+        name: string;
+        docs: string[];
+        discriminator: number[];
+        accounts: ({
+            name: string;
+            writable: boolean;
+            docs?: undefined;
+            signer?: undefined;
+        } | {
+            name: string;
+            docs: string[];
+            writable?: undefined;
+            signer?: undefined;
+        } | {
+            name: string;
+            docs: string[];
+            writable: boolean;
+            signer: boolean;
+        } | {
+            name: string;
+            writable?: undefined;
+            docs?: undefined;
+            signer?: undefined;
+        })[];
+        args: never[];
+    } | {
+        name: string;
+        docs: string[];
+        discriminator: number[];
+        accounts: ({
+            name: string;
+            docs: string[];
+            writable: boolean;
+            signer?: undefined;
+        } | {
+            name: string;
+            signer: boolean;
+            docs?: undefined;
+            writable?: undefined;
+        })[];
+        args: {
+            name: string;
+            type: {
+                vec: {
+                    defined: {
+                        name: string;
+                    };
+                };
+            };
+        }[];
     } | {
         name: string;
         docs: string[];
@@ -184,6 +269,37 @@ export declare const CUBIC_POOL_IDL: {
                 };
             })[];
         };
+    } | {
+        name: string;
+        type: {
+            kind: string;
+            fields: ({
+                name: string;
+                docs: string[];
+                type: string;
+            } | {
+                name: string;
+                type: string;
+                docs?: undefined;
+            } | {
+                name: string;
+                docs: string[];
+                type: {
+                    array: (number | {
+                        defined: {
+                            name: string;
+                        };
+                    })[];
+                };
+            } | {
+                name: string;
+                docs: string[];
+                type: {
+                    array: (string | number)[];
+                };
+            })[];
+        };
+        docs?: undefined;
     } | {
         name: string;
         docs: string[];
@@ -205,7 +321,11 @@ export declare const CUBIC_POOL_IDL: {
             kind: string;
             fields: {
                 name: string;
-                type: string;
+                type: {
+                    defined: {
+                        name: string;
+                    };
+                };
             }[];
         };
         docs?: undefined;
@@ -652,6 +772,91 @@ export declare const IDLS: {
                 name: string;
                 type: string;
             })[];
+        } | {
+            name: string;
+            docs: string[];
+            discriminator: number[];
+            accounts: ({
+                name: string;
+                docs: string[];
+                writable: boolean;
+                signer?: undefined;
+            } | {
+                name: string;
+                docs: string[];
+                writable?: undefined;
+                signer?: undefined;
+            } | {
+                name: string;
+                docs: string[];
+                signer: boolean;
+                writable?: undefined;
+            } | {
+                name: string;
+                docs: string[];
+                writable: boolean;
+                signer: boolean;
+            } | {
+                name: string;
+                docs?: undefined;
+                writable?: undefined;
+                signer?: undefined;
+            })[];
+            args: {
+                name: string;
+                type: string;
+            }[];
+        } | {
+            name: string;
+            docs: string[];
+            discriminator: number[];
+            accounts: ({
+                name: string;
+                writable: boolean;
+                docs?: undefined;
+                signer?: undefined;
+            } | {
+                name: string;
+                docs: string[];
+                writable?: undefined;
+                signer?: undefined;
+            } | {
+                name: string;
+                docs: string[];
+                writable: boolean;
+                signer: boolean;
+            } | {
+                name: string;
+                writable?: undefined;
+                docs?: undefined;
+                signer?: undefined;
+            })[];
+            args: never[];
+        } | {
+            name: string;
+            docs: string[];
+            discriminator: number[];
+            accounts: ({
+                name: string;
+                docs: string[];
+                writable: boolean;
+                signer?: undefined;
+            } | {
+                name: string;
+                signer: boolean;
+                docs?: undefined;
+                writable?: undefined;
+            })[];
+            args: {
+                name: string;
+                type: {
+                    vec: {
+                        defined: {
+                            name: string;
+                        };
+                    };
+                };
+            }[];
         } | {
             name: string;
             docs: string[];
@@ -738,6 +943,37 @@ export declare const IDLS: {
                     };
                 })[];
             };
+        } | {
+            name: string;
+            type: {
+                kind: string;
+                fields: ({
+                    name: string;
+                    docs: string[];
+                    type: string;
+                } | {
+                    name: string;
+                    type: string;
+                    docs?: undefined;
+                } | {
+                    name: string;
+                    docs: string[];
+                    type: {
+                        array: (number | {
+                            defined: {
+                                name: string;
+                            };
+                        })[];
+                    };
+                } | {
+                    name: string;
+                    docs: string[];
+                    type: {
+                        array: (string | number)[];
+                    };
+                })[];
+            };
+            docs?: undefined;
         } | {
             name: string;
             docs: string[];
@@ -759,7 +995,11 @@ export declare const IDLS: {
                 kind: string;
                 fields: {
                     name: string;
-                    type: string;
+                    type: {
+                        defined: {
+                            name: string;
+                        };
+                    };
                 }[];
             };
             docs?: undefined;

package/dist/idl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/idl/index.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAe,CAAC;AAC3C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAmB,CAAC;AACnD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA0B,CAAC;AAElE,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIP,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/idl/index.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAe,CAAC;AAC3C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAmB,CAAC;AACnD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA0B,CAAC;AAElE,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIP,CAAC"}

package/dist/types/result.d.ts

@@ -17,7 +17,7 @@ export interface SdkError {
     /** Original error for debugging; never render this to end users. */
     cause?: unknown;
 }
-export type SdkErrorCode = "rpc_unavailable" | "rpc_timeout" | "rpc_rate_limited" | "account_not_found" | "invalid_input" | "math_overflow" | "parse_failure" | "backend_unavailable" | "backend_invalid_response" | "insufficient_funds" | "pool_disabled" | "swaps_disabled" | "unsupported_pool_state" | "slippage_exceeded" | "simulation_failed" | "tx_build_failed" | "alt_fetch_failed" | "unknown";
+export type SdkErrorCode = "rpc_unavailable" | "rpc_timeout" | "rpc_rate_limited" | "account_not_found" | "invalid_input" | "math_overflow" | "parse_failure" | "backend_unavailable" | "backend_invalid_response" | "insufficient_funds" | "pool_disabled" | "swaps_disabled" | "unsupported_pool_state" | "slippage_exceeded" | "simulation_failed" | "tx_build_failed" | "alt_fetch_failed" | "auth_failed" | "unknown";
 export declare const ok: <T>(data: T) => SdkResult<T>;
 export declare const err: (code: SdkErrorCode, humanMessage: string, cause?: unknown) => SdkResult<never>;
 //# sourceMappingURL=result.d.ts.map

package/dist/types/result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,aAAa,GACb,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,eAAe,GACf,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,eAAe,GACf,gBAAgB,GAChB,wBAAwB,GACxB,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,kBAAkB,GAClB,SAAS,CAAC;AAEd,eAAO,MAAM,EAAE,GAAI,CAAC,EAAE,MAAM,CAAC,KAAG,SAAS,CAAC,CAAC,CAAyB,CAAC;AACrE,eAAO,MAAM,GAAG,GACd,MAAM,YAAY,EAClB,cAAc,MAAM,EACpB,QAAQ,OAAO,KACd,SAAS,CAAC,KAAK,CAGhB,CAAC"}
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,aAAa,GACb,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,eAAe,GACf,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,eAAe,GACf,gBAAgB,GAChB,wBAAwB,GACxB,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,SAAS,CAAC;AAEd,eAAO,MAAM,EAAE,GAAI,CAAC,EAAE,MAAM,CAAC,KAAG,SAAS,CAAC,CAAC,CAAyB,CAAC;AACrE,eAAO,MAAM,GAAG,GACd,MAAM,YAAY,EAClB,cAAc,MAAM,EACpB,QAAQ,OAAO,KACd,SAAS,CAAC,KAAK,CAGhB,CAAC"}

package/dist/types/result.js.map

@@ -1 +1 @@
-{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":";;;AAqCO,MAAM,EAAE,GAAG,CAAI,IAAO,EAAgB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAAxD,QAAA,EAAE,MAAsD;AAC9D,MAAM,GAAG,GAAG,CACjB,IAAkB,EAClB,YAAoB,EACpB,KAAe,EACG,EAAE,CAAC,CAAC;IACtB,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE;CACrC,CAAC,CAAC;AAPU,QAAA,GAAG,OAOb"}
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":";;;AAsCO,MAAM,EAAE,GAAG,CAAI,IAAO,EAAgB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAAxD,QAAA,EAAE,MAAsD;AAC9D,MAAM,GAAG,GAAG,CACjB,IAAkB,EAClB,YAAoB,EACpB,KAAe,EACG,EAAE,CAAC,CAAC;IACtB,EAAE,EAAE,KAAK;IACT,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE;CACrC,CAAC,CAAC;AAPU,QAAA,GAAG,OAOb"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubee_ee/sdk",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "publishConfig": {
     "access": "public"
   },

package/src/clients/CubeBackendClient.ts

@@ -6,6 +6,16 @@ export interface CubeBackendClientParams {
   apiEndpoint: string;
   apiKey?: string;
   defaultHeaders?: Record<string, string>;
+  /**
+   * Called when tokens are refreshed automatically after a 401.
+   * The frontend should persist the new tokens (e.g. to localStorage).
+   */
+  onTokenRefreshed?: (tokens: AuthTokens) => void;
+  /**
+   * Called when both access and refresh tokens are expired/invalid.
+   * The frontend should trigger a full re-authentication (SIWS sign-in).
+   */
+  onAuthExpired?: () => void;
 }
 
 export type StatsKind =
@@ -131,14 +141,36 @@ export interface LeaderboardEpochResponse {
   epochs: EpochHistoryEntry[];
 }
 
+// ── Auth types ──
+
+export interface NonceResponse {
+  nonce: string;
+  message: string;
+}
+
+export interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  wallet: string;
+  expiresIn: string;
+}
+
 /**
  * REST wrapper around the Cube backend. Every method is a SdkResult; no
  * exceptions escape. If a request fails, the result carries a
  * human-readable error plus the original cause.
+ *
+ * Auto-refresh: when a request gets 401, the client automatically tries
+ * to refresh tokens via POST /api/auth/refresh. If successful, the
+ * original request is retried once with the new access token.
  */
 export class CubeBackendClient {
   private readonly endpoint: string;
   private readonly headers: Record<string, string>;
+  private refreshToken: string | null = null;
+  private refreshInFlight: Promise<boolean> | null = null;
+  private readonly onTokenRefreshed?: (tokens: AuthTokens) => void;
+  private readonly onAuthExpired?: () => void;
 
   constructor(params: CubeBackendClientParams) {
     this.endpoint = params.apiEndpoint.replace(/\/$/, "");
@@ -147,6 +179,8 @@ export class CubeBackendClient {
       ...(params.apiKey ? { Authorization: `Bearer ${params.apiKey}` } : {}),
       ...(params.defaultHeaders ?? {}),
     };
+    this.onTokenRefreshed = params.onTokenRefreshed;
+    this.onAuthExpired = params.onAuthExpired;
   }
 
   listPools(): Promise<SdkResult<PoolSummary[]>> {
@@ -280,16 +314,90 @@ export class CubeBackendClient {
     return this.get<StatsSeries>(`/api/stats/${kind}?${qs.toString()}`);
   }
 
+  // ── Auth ──
+
+  /** Request a SIWS nonce + pre-built message for the given wallet. */
+  getNonce(wallet: string): Promise<SdkResult<NonceResponse>> {
+    return this.get<NonceResponse>(
+      `/api/auth/nonce?wallet=${encodeURIComponent(wallet)}`,
+    );
+  }
+
+  /** Submit signed SIWS message to receive access + refresh tokens. */
+  verifySignature(
+    message: string,
+    signature: string,
+  ): Promise<SdkResult<AuthTokens>> {
+    return this.post<AuthTokens>("/api/auth/verify", {
+      message,
+      signature,
+    });
+  }
+
+  /**
+   * Set both tokens. Call this after verifySignature() and on app init
+   * (restoring tokens from storage).
+   */
+  setTokens(accessToken: string, refreshToken: string): void {
+    this.headers["Authorization"] = `Bearer ${accessToken}`;
+    this.refreshToken = refreshToken;
+  }
+
+  /** Clear both tokens (logout). */
+  clearTokens(): void {
+    delete this.headers["Authorization"];
+    this.refreshToken = null;
+  }
+
+  /** @deprecated Use setTokens() instead. */
+  setAccessToken(token: string): void {
+    this.headers["Authorization"] = `Bearer ${token}`;
+  }
+
+  /** @deprecated Use clearTokens() instead. */
+  clearAccessToken(): void {
+    delete this.headers["Authorization"];
+    this.refreshToken = null;
+  }
+
   /** Generic GET with retry. Callers that need it for other endpoints. */
   get<T>(path: string): Promise<SdkResult<T>> {
-    return this.request<T>("GET", path);
+    return this.requestWithRefresh<T>("GET", path);
   }
 
   post<T>(path: string, body: unknown): Promise<SdkResult<T>> {
-    return this.request<T>("POST", path, body);
+    return this.requestWithRefresh<T>("POST", path, body);
+  }
+
+  // ── Private: HTTP layer with auto-refresh ──
+
+  /**
+   * Core request method with auto-refresh on 401.
+   * If a request gets 401 and we have a refresh token:
+   *   1. Call POST /api/auth/refresh (deduplicated if concurrent)
+   *   2. On success: update tokens, notify via callback, retry original request
+   *   3. On failure: notify via onAuthExpired callback, return original error
+   */
+  private async requestWithRefresh<T>(
+    method: "GET" | "POST",
+    path: string,
+    body?: unknown,
+  ): Promise<SdkResult<T>> {
+    const result = await this.rawRequest<T>(method, path, body);
+
+    // Don't auto-refresh for auth endpoints themselves
+    const isAuthPath = path.startsWith("/api/auth/");
+    if (!isAuthPath && !result.ok && this.is401(result) && this.refreshToken) {
+      const refreshed = await this.tryRefresh();
+      if (refreshed) {
+        return this.rawRequest<T>(method, path, body);
+      }
+    }
+
+    return result;
   }
 
-  private async request<T>(
+  private async rawRequest<T>(
     method: "GET" | "POST",
     path: string,
     body?: unknown
@@ -303,7 +411,11 @@ export class CubeBackendClient {
     const raw = await safeCall(async () => {
       const res = await fetch(url, fetchOpts);
       if (!res.ok) {
-        throw new Error(`${method} ${path} → HTTP ${res.status} ${res.statusText}`);
+        const error = new Error(
+          `${method} ${path} → HTTP ${res.status} ${res.statusText}`,
+        );
+        (error as any).status = res.status;
+        throw error;
       }
       return (await res.json()) as T;
     });
@@ -311,6 +423,46 @@ export class CubeBackendClient {
     return ok(raw.data);
   }
 
+  /**
+   * Attempt to refresh tokens. Returns true if successful.
+   * Deduplicates concurrent refresh attempts.
+   */
+  private async tryRefresh(): Promise<boolean> {
+    // Deduplicate: if a refresh is already in flight, wait for it
+    if (this.refreshInFlight) {
+      return this.refreshInFlight;
+    }
+
+    this.refreshInFlight = this.doRefresh();
+    try {
+      return await this.refreshInFlight;
+    } finally {
+      this.refreshInFlight = null;
+    }
+  }
+
+  private async doRefresh(): Promise<boolean> {
+    const res = await this.rawRequest<AuthTokens>("POST", "/api/auth/refresh", {
+      refreshToken: this.refreshToken,
+    });
+
+    if (res.ok) {
+      this.setTokens(res.data.accessToken, res.data.refreshToken);
+      this.onTokenRefreshed?.(res.data);
+      return true;
+    }
+
+    // Refresh failed — both tokens are dead
+    this.clearTokens();
+    this.onAuthExpired?.();
+    return false;
+  }
+
+  private is401(result: SdkResult<unknown>): boolean {
+    if (result.ok) return false;
+    return result.error.humanMessage.includes("HTTP 401");
+  }
+
   /**
    * Fetch a response envelope of the form `{ data: T, ... }` and unwrap
    * the `.data` field. The existing Cube backend wraps most endpoints