@oxyhq/core 3.16.1 → 3.17.1

package/dist/types/OxyServices.base.d.ts

@@ -142,6 +142,17 @@ export declare class OxyServicesBase {
      * Get the raw access token (for constructing anchor URLs when needed)
      */
     getAccessToken(): string | null;
+    /**
+     * Decode the current access token and return its `exp` claim in SECONDS since
+     * the Unix epoch (the raw JWT `exp` unit), or `null` when there is no token,
+     * the token is opaque/undecodable, or it carries no numeric `exp`.
+     *
+     * Exposed so `@oxyhq/services` can schedule a PROACTIVE in-session refresh a
+     * fixed lead before expiry without re-importing a JWT decoder (and without
+     * duplicating the `jwt-decode` dependency in the RN bundle). HttpService keeps
+     * the per-request preflight refresh; this powers the idle/background timer.
+     */
+    getAccessTokenExpiry(): number | null;
     /**
      * Set the acting-as identity for managed accounts.
      *

package/dist/types/index.d.ts

@@ -20,6 +20,7 @@ import './crypto/polyfill';
 export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
+export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 export { AuthManager, createAuthManager } from './AuthManager';
 export type { StorageAdapter, AuthStateChangeCallback, AuthMethod, AuthManagerConfig, } from './AuthManager';
 export type { AuthManagerAccount, RestoreFromCookiesResult, RestoreFromCookiesOptions, SwitchAuthuserResult, } from './AuthManagerTypes';

package/dist/types/mixins/OxyServices.analytics.d.ts

@@ -54,6 +54,7 @@ export declare function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBa
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.appData.d.ts

@@ -90,6 +90,7 @@ export declare function OxyServicesAppDataMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.applications.d.ts

@@ -475,6 +475,7 @@ export declare function OxyServicesApplicationsMixin<T extends typeof OxyService
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -134,6 +134,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -569,6 +569,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.civic.d.ts

@@ -492,6 +492,7 @@ export declare function OxyServicesCivicMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.contacts.d.ts

@@ -82,6 +82,7 @@ export declare function OxyServicesContactsMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.devices.d.ts

@@ -84,6 +84,7 @@ export declare function OxyServicesDevicesMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.features.d.ts

@@ -232,6 +232,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -286,6 +286,7 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.identity.d.ts

@@ -229,6 +229,7 @@ export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.language.d.ts

@@ -69,6 +69,7 @@ export declare function OxyServicesLanguageMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.links.d.ts

@@ -37,11 +37,15 @@ export declare function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(
          * Resolve multiple link previews via `POST /links/previews` (body `{ urls }`).
          *
          * Inputs are de-duplicated and split into chunks of {@link LINK_PREVIEWS_CHUNK_SIZE}
-         * (the server-side cap). Chunks run concurrently and their `data` maps are
+         * (the server-side cap). Chunks run concurrently and their result maps are
          * merged into a single result keyed by the REQUESTED url (the exact string
          * passed in `urls`) — matching the batch contract — so a caller can always
          * look its own input back up.
          *
+         * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
+         * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
+         * already the `Record<url, LinkPreview>` map — merge it directly.
+         *
          * An empty / whitespace-only input resolves immediately with `{}` and
          * performs no network call. A failure in any chunk surfaces (via
          * `handleError`) rather than being swallowed.
@@ -82,6 +86,7 @@ export declare function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.location.d.ts

@@ -52,6 +52,7 @@ export declare function OxyServicesLocationMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.managedAccounts.d.ts

@@ -124,6 +124,7 @@ export declare function OxyServicesManagedAccountsMixin<T extends typeof OxyServ
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.nodes.d.ts

@@ -222,6 +222,7 @@ export declare function OxyServicesNodesMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.payment.d.ts

@@ -99,6 +99,7 @@ export declare function OxyServicesPaymentMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.privacy.d.ts

@@ -128,6 +128,7 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.redirect.d.ts

@@ -71,6 +71,7 @@ export declare function OxyServicesRedirectAuthMixin<T extends typeof OxyService
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.reputation.d.ts

@@ -417,6 +417,7 @@ export declare function OxyServicesReputationMixin<T extends typeof OxyServicesB
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.security.d.ts

@@ -66,6 +66,7 @@ export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.silent.d.ts

@@ -109,6 +109,7 @@ export declare function OxyServicesSilentAuthMixin<T extends typeof OxyServicesB
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.sso.d.ts

@@ -94,6 +94,7 @@ export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Ba
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.topics.d.ts

@@ -92,6 +92,7 @@ export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -363,6 +363,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -277,6 +277,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/dist/types/mixins/OxyServices.workspaces.d.ts

@@ -198,6 +198,7 @@ export declare function OxyServicesWorkspacesMixin<T extends typeof OxyServicesB
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
         setActingAs(userId: string | null): void;
         getActingAs(): string | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.16.1",
+  "version": "3.17.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -524,7 +524,14 @@ export class HttpService {
           if (response.status === 401 && !config._isAuthRetry) {
             const refreshed = await this.refreshAccessToken('response-401');
             if (refreshed) {
-              return this.request<T>({ ...config, _isAuthRetry: true, retry: false });
+              // `deduplicate: false` is REQUIRED on the retry (mirrors the 403
+              // CSRF retry below). This re-issue runs while the ORIGINAL request
+              // is still in-flight under its dedupe key; the refreshed token is
+              // for the SAME user, so the identity-scoped key is UNCHANGED — a
+              // deduplicated retry would resolve to the still-pending original
+              // and await itself (deadlock). Opting the retry out of dedupe makes
+              // it a fresh request.
+              return this.request<T>({ ...config, _isAuthRetry: true, retry: false, deduplicate: false });
             }
             // Refresh failed or no token — clear tokens and stale CSRF
             this.tokenStore.clearTokens();

package/src/OxyServices.base.ts

@@ -310,6 +310,31 @@ export class OxyServicesBase {
     return this.httpService.getAccessToken();
   }
 
+  /**
+   * Decode the current access token and return its `exp` claim in SECONDS since
+   * the Unix epoch (the raw JWT `exp` unit), or `null` when there is no token,
+   * the token is opaque/undecodable, or it carries no numeric `exp`.
+   *
+   * Exposed so `@oxyhq/services` can schedule a PROACTIVE in-session refresh a
+   * fixed lead before expiry without re-importing a JWT decoder (and without
+   * duplicating the `jwt-decode` dependency in the RN bundle). HttpService keeps
+   * the per-request preflight refresh; this powers the idle/background timer.
+   */
+  public getAccessTokenExpiry(): number | null {
+    const token = this.httpService.getAccessToken();
+    if (!token) {
+      return null;
+    }
+    try {
+      const decoded = jwtDecode<JwtPayload>(token);
+      return typeof decoded.exp === 'number' ? decoded.exp : null;
+    } catch {
+      // A malformed / non-JWT token has no usable expiry — fall back to the
+      // reactive 401 refresh path instead of a scheduled one.
+      return null;
+    }
+  }
+
   /**
    * Set the acting-as identity for managed accounts.
    *

package/src/__tests__/inSessionRefresh.test.ts

@@ -0,0 +1,193 @@
+/**
+ * In-session access-token refresh plumbing.
+ *
+ * These guard the HttpService surface that `@oxyhq/services`' OxyContext now
+ * drives via `setAuthRefreshHandler`: a 401 re-mints through the handler and
+ * retries the ORIGINAL request with the fresh token; an unrecoverable refresh
+ * clears tokens and notifies listeners (the reconcile signal that flips the RN
+ * provider out of its zombie logged-in state); concurrent refreshes coalesce and
+ * a failed refresh is cooldown-guarded (no refresh storm). Plus the new
+ * `OxyServices.getAccessTokenExpiry()` helper the proactive scheduler reads.
+ */
+import { HttpService } from '../HttpService';
+import { OxyServices } from '../OxyServices';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function unauthorized(): Response {
+  return new Response(JSON.stringify({ error: 'token expired' }), {
+    status: 401,
+    statusText: 'Unauthorized',
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function readHeaders(init: RequestInit | undefined): Record<string, string> {
+  const headers = init?.headers;
+  if (!headers) return {};
+  if (headers instanceof Headers) return Object.fromEntries(headers.entries());
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  return headers as Record<string, string>;
+}
+
+const farFutureExp = (): number => Math.floor(Date.now() / 1000) + 3600;
+
+describe('HttpService in-session refresh handler', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('refreshes via the handler on a 401 and retries the original request with the fresh token', async () => {
+    const oldToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'old' });
+    const newToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'new' });
+    const calls: FetchCall[] = [];
+    let feedAttempts = 0;
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
+      calls.push({ url, init });
+      if (url.endsWith('/feed')) {
+        feedAttempts += 1;
+        if (feedAttempts === 1) return unauthorized();
+      }
+      return jsonResponse({ ok: true });
+    };
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(oldToken);
+
+    let handlerCalls = 0;
+    const reasons: string[] = [];
+    http.setAuthRefreshHandler(async (reason) => {
+      handlerCalls += 1;
+      reasons.push(reason);
+      // Simulate a silent arm planting the rotated token internally.
+      http.setTokens(newToken);
+      return newToken;
+    });
+
+    const result = await http.post('/feed', { cursor: 0 }, { retry: false });
+
+    expect(result).toEqual({ ok: true });
+    expect(handlerCalls).toBe(1);
+    expect(reasons).toEqual(['response-401']);
+
+    const feedCalls = calls.filter((call) => call.url.endsWith('/feed'));
+    expect(feedCalls).toHaveLength(2);
+    // The original request is retried carrying the FRESH bearer.
+    expect(readHeaders(feedCalls[1].init).Authorization).toBe(`Bearer ${newToken}`);
+    expect(http.getAccessToken()).toBe(newToken);
+  });
+
+  it('clears tokens and notifies listeners when the handler cannot refresh on a 401 (reconcile signal)', async () => {
+    globalThis.fetch = async (input) => {
+      const url = String(input);
+      if (url.endsWith('/feed')) return unauthorized();
+      return jsonResponse({ ok: true });
+    };
+
+    const oxy = new OxyServices({ baseURL: 'https://api.mention.earth' });
+    oxy.setTokens(createJwt({ userId: 'u', exp: farFutureExp() }));
+
+    const tokenEvents: Array<string | null> = [];
+    oxy.onTokensChanged((token) => tokenEvents.push(token));
+
+    oxy.getClient().setAuthRefreshHandler(async () => null);
+
+    await expect(oxy.getClient().post('/feed', {}, { retry: false })).rejects.toBeDefined();
+
+    // The dead session reconciles: token cleared + a null change emitted (which
+    // OxyContext's `handleTokenChange(null)` turns into a local sign-out).
+    expect(oxy.getAccessToken()).toBeNull();
+    expect(tokenEvents).toContain(null);
+  });
+
+  it('coalesces concurrent refreshes into a single handler invocation', async () => {
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+    const newToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'fresh' });
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: farFutureExp() }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      http.setTokens(newToken);
+      return newToken;
+    });
+
+    const [a, b, c] = await Promise.all([
+      http.refreshAccessToken('preflight'),
+      http.refreshAccessToken('preflight'),
+      http.refreshAccessToken('preflight'),
+    ]);
+
+    expect(handlerCalls).toBe(1);
+    expect([a, b, c]).toEqual([newToken, newToken, newToken]);
+  });
+
+  it('cooldown-guards a failed refresh so it does not storm the handler', async () => {
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: farFutureExp() }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      return null;
+    });
+
+    const first = await http.refreshAccessToken('preflight');
+    const second = await http.refreshAccessToken('preflight');
+
+    expect(first).toBeNull();
+    expect(second).toBeNull();
+    // The second call is inside the post-failure cooldown → handler not re-run.
+    expect(handlerCalls).toBe(1);
+  });
+});
+
+describe('OxyServices.getAccessTokenExpiry', () => {
+  it('returns the JWT exp (seconds) of the current access token', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const exp = Math.floor(Date.now() / 1000) + 1234;
+    oxy.setTokens(createJwt({ userId: 'u', exp }));
+    expect(oxy.getAccessTokenExpiry()).toBe(exp);
+  });
+
+  it('returns null when there is no access token', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    expect(oxy.getAccessTokenExpiry()).toBeNull();
+  });
+
+  it('returns null for an opaque / non-JWT token', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens('opaque-not-a-jwt');
+    expect(oxy.getAccessTokenExpiry()).toBeNull();
+  });
+
+  it('returns null for a JWT with no numeric exp claim', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(createJwt({ userId: 'u' }));
+    expect(oxy.getAccessTokenExpiry()).toBeNull();
+  });
+});

package/src/index.ts

@@ -26,6 +26,10 @@ import './crypto/polyfill';
 export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
+// Auth-refresh handler surface — consumed by `@oxyhq/services`'s OxyContext to
+// install an in-session access-token refresh handler on the owner HttpService
+// (the linked-client refresh path delegates back to it).
+export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 
 // ---------------------------------------------------------------------------
 // Authentication

package/src/mixins/OxyServices.links.ts

@@ -15,7 +15,7 @@
  * later read, so an SDK GET cache would pin the stale `'pending'` snapshot.
  * App-side caching (React Query / stores) owns this responsibility.
  */
-import type { LinkPreview, LinkPreviewBatchResponse } from '@oxyhq/contracts';
+import type { LinkPreview } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { buildUrl } from '../utils/apiUtils';
 
@@ -57,11 +57,15 @@ export function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(Base: T)
      * Resolve multiple link previews via `POST /links/previews` (body `{ urls }`).
      *
      * Inputs are de-duplicated and split into chunks of {@link LINK_PREVIEWS_CHUNK_SIZE}
-     * (the server-side cap). Chunks run concurrently and their `data` maps are
+     * (the server-side cap). Chunks run concurrently and their result maps are
      * merged into a single result keyed by the REQUESTED url (the exact string
      * passed in `urls`) — matching the batch contract — so a caller can always
      * look its own input back up.
      *
+     * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
+     * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
+     * already the `Record<url, LinkPreview>` map — merge it directly.
+     *
      * An empty / whitespace-only input resolves immediately with `{}` and
      * performs no network call. A failure in any chunk surfaces (via
      * `handleError`) rather than being swallowed.
@@ -82,7 +86,7 @@ export function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(Base: T)
       try {
         const responses = await Promise.all(
           chunks.map((chunk) =>
-            this.makeRequest<LinkPreviewBatchResponse>(
+            this.makeRequest<Record<string, LinkPreview>>(
               'POST',
               '/links/previews',
               { urls: chunk },
@@ -92,7 +96,7 @@ export function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(Base: T)
         );
 
         return responses.reduce<Record<string, LinkPreview>>(
-          (merged, response) => Object.assign(merged, response?.data ?? {}),
+          (merged, response) => Object.assign(merged, response ?? {}),
           {},
         );
       } catch (error) {