@vercel/sandbox 0.0.17 → 0.0.18

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.17 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.18 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.17 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.18 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/sandbox
 
+## 0.0.18
+
+### Patch Changes
+
+- refresh oidc token if stale in development ([#106](https://github.com/vercel/sandbox-sdk/pull/106))
+
 ## 0.0.17
 
 ### Patch Changes

package/dist/api-client/api-client.d.ts

@@ -4,11 +4,13 @@ import { FileWriter } from "./file-writer";
 import { z } from "zod";
 export declare class APIClient extends BaseClient {
     private teamId;
+    private tokenExpiry;
     constructor(params: {
         host?: string;
         teamId: string;
         token: string;
     });
+    private ensureValidToken;
     protected request(path: string, params?: RequestParams): Promise<Response>;
     getSandbox(params: {
         sandboxId: string;

package/dist/api-client/api-client.js

@@ -14,6 +14,7 @@ const jsonlines_1 = __importDefault(require("jsonlines"));
 const os_1 = __importDefault(require("os"));
 const stream_1 = require("stream");
 const normalizePath_1 = require("../utils/normalizePath");
+const jwt_expiry_1 = require("../utils/jwt-expiry");
 class APIClient extends base_client_1.BaseClient {
     constructor(params) {
         super({
@@ -22,8 +23,24 @@ class APIClient extends base_client_1.BaseClient {
             debug: false,
         });
         this.teamId = params.teamId;
+        this.tokenExpiry = jwt_expiry_1.JwtExpiry.fromToken(params.token);
+    }
+    async ensureValidToken() {
+        if (!this.tokenExpiry) {
+            return;
+        }
+        const newExpiry = await this.tokenExpiry.tryRefresh();
+        if (!newExpiry) {
+            return;
+        }
+        this.tokenExpiry = newExpiry;
+        this.token = this.tokenExpiry.token;
+        if (this.tokenExpiry.payload) {
+            this.teamId = this.tokenExpiry.payload?.owner_id;
+        }
     }
     async request(path, params) {
+        await this.ensureValidToken();
         return super.request(path, {
             ...params,
             query: { teamId: this.teamId, ...params?.query },

package/dist/sandbox.js

@@ -30,7 +30,7 @@ class Sandbox {
      * @returns A promise resolving to the created {@link Sandbox}.
      */
     static async create(params) {
-        const credentials = (0, get_credentials_1.getCredentials)(params);
+        const credentials = await (0, get_credentials_1.getCredentials)(params);
         const client = new api_client_1.APIClient({
             teamId: credentials.teamId,
             token: credentials.token,
@@ -56,7 +56,7 @@ class Sandbox {
      * @returns A promise resolving to the {@link Sandbox}.
      */
     static async get(params) {
-        const credentials = (0, get_credentials_1.getCredentials)(params);
+        const credentials = await (0, get_credentials_1.getCredentials)(params);
         const client = new api_client_1.APIClient({
             teamId: credentials.teamId,
             token: credentials.token,

package/dist/utils/get-credentials.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export interface Credentials {
     /**
      * Authentication token for the Vercel API. It could be an OIDC token
@@ -23,4 +24,24 @@ export interface Credentials {
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-export declare function getCredentials<T>(params?: T | Credentials): Credentials;
+export declare function getCredentials(params?: unknown): Promise<Credentials>;
+/**
+ * Schema to validate the payload of the Vercel OIDC token where we expect
+ * to find the `teamId` and `projectId`.
+ */
+export declare const schema: z.ZodObject<{
+    exp: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+    owner_id: z.ZodString;
+    project_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    owner_id: string;
+    project_id: string;
+    exp?: number | undefined;
+    iat?: number | undefined;
+}, {
+    owner_id: string;
+    project_id: string;
+    exp?: number | undefined;
+    iat?: number | undefined;
+}>;

package/dist/utils/get-credentials.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
 exports.getCredentials = getCredentials;
 const oidc_1 = require("@vercel/oidc");
 const decode_base64_url_1 = require("./decode-base64-url");
@@ -14,12 +15,12 @@ const zod_1 = require("zod");
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-function getCredentials(params) {
+async function getCredentials(params) {
     const credentials = getCredentialsFromParams(params ?? {});
     if (credentials) {
         return credentials;
     }
-    const oidcToken = (0, oidc_1.getVercelOidcTokenSync)();
+    const oidcToken = await (0, oidc_1.getVercelOidcToken)();
     if (oidcToken) {
         return getCredentialsFromOIDCToken(oidcToken);
     }
@@ -32,6 +33,10 @@ function getCredentials(params) {
  * or none of them, otherwise an error is thrown.
  */
 function getCredentialsFromParams(params) {
+    // Type guard: params must be an object
+    if (!params || typeof params !== "object") {
+        return null;
+    }
     const missing = [
         "token" in params && typeof params.token === "string" ? null : "token",
         "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
@@ -57,7 +62,9 @@ function getCredentialsFromParams(params) {
  * Schema to validate the payload of the Vercel OIDC token where we expect
  * to find the `teamId` and `projectId`.
  */
-const schema = zod_1.z.object({
+exports.schema = zod_1.z.object({
+    exp: zod_1.z.number().optional().describe("Expiry timestamp (seconds since epoch)"),
+    iat: zod_1.z.number().optional().describe("Issued at timestamp"),
     owner_id: zod_1.z.string(),
     project_id: zod_1.z.string(),
 });
@@ -71,7 +78,7 @@ const schema = zod_1.z.object({
  */
 function getCredentialsFromOIDCToken(token) {
     try {
-        const payload = schema.parse((0, decode_base64_url_1.decodeBase64Url)(token.split(".")[1]));
+        const payload = exports.schema.parse((0, decode_base64_url_1.decodeBase64Url)(token.split(".")[1]));
         return {
             token,
             projectId: payload.project_id,

package/dist/utils/jwt-expiry.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { schema } from "./get-credentials";
+export declare class OidcRefreshError extends Error {
+    name: string;
+}
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+export declare class JwtExpiry {
+    readonly token: string;
+    private expiryTime;
+    readonly payload?: Readonly<z.infer<typeof schema>>;
+    static fromToken(token: string): JwtExpiry | null;
+    /**
+     * Creates a new JWT expiry checker.
+     *
+     * @param token - The JWT token to parse
+     */
+    constructor(token: string);
+    /**
+     * Checks if the JWT token is valid (not expired).
+     * @returns true if token is valid, false if expired or expiring soon
+     */
+    isValid(): boolean;
+    /**
+     * Gets the expiry date of the JWT token.
+     *
+     * @returns Date object representing when the token expires, or null if no expiry
+     */
+    getExpiryDate(): Date | null;
+    /**
+     * Refreshes the JWT token by fetching a new OIDC token.
+     *
+     * @returns Promise resolving to a new JwtExpiry instance with fresh token
+     */
+    refresh(): Promise<JwtExpiry>;
+    /**
+     * Refreshes the JWT token if it's expired or expiring soon.
+     */
+    tryRefresh(): Promise<JwtExpiry | null>;
+}

package/dist/utils/jwt-expiry.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtExpiry = exports.OidcRefreshError = void 0;
+const decode_base64_url_1 = require("./decode-base64-url");
+const get_credentials_1 = require("./get-credentials");
+const oidc_1 = require("@vercel/oidc");
+const ms_1 = __importDefault(require("ms"));
+/** Time buffer before token expiry to consider it invalid (in milliseconds) */
+const BUFFER_MS = (0, ms_1.default)("5m");
+class OidcRefreshError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "OidcRefreshError";
+    }
+}
+exports.OidcRefreshError = OidcRefreshError;
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+class JwtExpiry {
+    static fromToken(token) {
+        if (!isJwtFormat(token)) {
+            return null;
+        }
+        else {
+            return new JwtExpiry(token);
+        }
+    }
+    /**
+     * Creates a new JWT expiry checker.
+     *
+     * @param token - The JWT token to parse
+     */
+    constructor(token) {
+        this.token = token;
+        try {
+            const tokenContents = token.split(".")[1];
+            this.payload = get_credentials_1.schema.parse((0, decode_base64_url_1.decodeBase64Url)(tokenContents));
+            this.expiryTime = this.payload.exp || null;
+        }
+        catch {
+            // Malformed token - treat as expired to trigger refresh
+            this.expiryTime = 0;
+        }
+    }
+    /**
+     * Checks if the JWT token is valid (not expired).
+     * @returns true if token is valid, false if expired or expiring soon
+     */
+    isValid() {
+        if (this.expiryTime === null) {
+            return false; // No expiry means malformed JWT
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const buffer = BUFFER_MS / 1000;
+        return now + buffer < this.expiryTime;
+    }
+    /**
+     * Gets the expiry date of the JWT token.
+     *
+     * @returns Date object representing when the token expires, or null if no expiry
+     */
+    getExpiryDate() {
+        return this.expiryTime ? new Date(this.expiryTime * 1000) : null;
+    }
+    /**
+     * Refreshes the JWT token by fetching a new OIDC token.
+     *
+     * @returns Promise resolving to a new JwtExpiry instance with fresh token
+     */
+    async refresh() {
+        try {
+            const freshToken = await (0, oidc_1.getVercelOidcToken)();
+            return new JwtExpiry(freshToken);
+        }
+        catch (cause) {
+            throw new OidcRefreshError("Failed to refresh OIDC token", {
+                cause,
+            });
+        }
+    }
+    /**
+     * Refreshes the JWT token if it's expired or expiring soon.
+     */
+    async tryRefresh() {
+        if (this.isValid()) {
+            return null; // Still valid, no need to refresh
+        }
+        return this.refresh();
+    }
+}
+exports.JwtExpiry = JwtExpiry;
+/**
+ * Checks if a token follows JWT format (has 3 parts separated by dots).
+ *
+ * @param token - The token to check
+ * @returns true if token appears to be a JWT, false otherwise
+ */
+function isJwtFormat(token) {
+    return token.split(".").length === 3;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.17";
+export declare const VERSION = "0.0.18";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "0.0.17";
+exports.VERSION = "0.0.18";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@vercel/oidc": "^2.0.0",
+    "@vercel/oidc": "^2.0.2",
     "async-retry": "1.3.3",
     "jsonlines": "0.1.1",
     "ms": "2.1.3",

package/src/api-client/api-client.ts

@@ -21,9 +21,11 @@ import jsonlines from "jsonlines";
 import os from "os";
 import { Readable } from "stream";
 import { normalizePath } from "../utils/normalizePath";
+import { JwtExpiry } from "../utils/jwt-expiry";
 
 export class APIClient extends BaseClient {
   private teamId: string;
+  private tokenExpiry: JwtExpiry | null;
 
   constructor(params: { host?: string; teamId: string; token: string }) {
     super({
@@ -33,9 +35,29 @@ export class APIClient extends BaseClient {
     });
 
     this.teamId = params.teamId;
+    this.tokenExpiry = JwtExpiry.fromToken(params.token);
+  }
+
+  private async ensureValidToken(): Promise<void> {
+    if (!this.tokenExpiry) {
+      return;
+    }
+
+    const newExpiry = await this.tokenExpiry.tryRefresh();
+    if (!newExpiry) {
+      return;
+    }
+
+    this.tokenExpiry = newExpiry;
+    this.token = this.tokenExpiry.token;
+    if (this.tokenExpiry.payload) {
+      this.teamId = this.tokenExpiry.payload?.owner_id;
+    }
   }
 
   protected async request(path: string, params?: RequestParams) {
+    await this.ensureValidToken();
+
     return super.request(path, {
       ...params,
       query: { teamId: this.teamId, ...params?.query },

package/src/sandbox.ts

@@ -142,7 +142,7 @@ export class Sandbox {
   static async create(
     params?: CreateSandboxParams | (CreateSandboxParams & Credentials),
   ): Promise<Sandbox> {
-    const credentials = getCredentials(params);
+    const credentials = await getCredentials(params);
     const client = new APIClient({
       teamId: credentials.teamId,
       token: credentials.token,
@@ -173,7 +173,7 @@ export class Sandbox {
   static async get(
     params: GetSandboxParams | (GetSandboxParams & Credentials),
   ): Promise<Sandbox> {
-    const credentials = getCredentials(params);
+    const credentials = await getCredentials(params);
     const client = new APIClient({
       teamId: credentials.teamId,
       token: credentials.token,

package/src/utils/get-credentials.ts

@@ -1,4 +1,4 @@
-import { getVercelOidcTokenSync } from "@vercel/oidc";
+import { getVercelOidcToken } from "@vercel/oidc";
 import { decodeBase64Url } from "./decode-base64-url";
 import { z } from "zod";
 
@@ -28,13 +28,13 @@ export interface Credentials {
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-export function getCredentials<T>(params?: T | Credentials): Credentials {
+export async function getCredentials(params?: unknown): Promise<Credentials> {
   const credentials = getCredentialsFromParams(params ?? {});
   if (credentials) {
     return credentials;
   }
 
-  const oidcToken = getVercelOidcTokenSync();
+  const oidcToken = await getVercelOidcToken();
   if (oidcToken) {
     return getCredentialsFromOIDCToken(oidcToken);
   }
@@ -50,9 +50,12 @@ export function getCredentials<T>(params?: T | Credentials): Credentials {
  * required fields (`token`, `teamId`, and `projectId`) must be present
  * or none of them, otherwise an error is thrown.
  */
-function getCredentialsFromParams<Params extends Record<string, unknown>>(
-  params: Params | Credentials,
-): Credentials | null {
+function getCredentialsFromParams(params: unknown): Credentials | null {
+  // Type guard: params must be an object
+  if (!params || typeof params !== "object") {
+    return null;
+  }
+
   const missing = [
     "token" in params && typeof params.token === "string" ? null : "token",
     "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
@@ -63,9 +66,9 @@ function getCredentialsFromParams<Params extends Record<string, unknown>>(
 
   if (missing.length === 0) {
     return {
-      token: params.token as string,
-      projectId: params.projectId as string,
-      teamId: params.teamId as string,
+      token: (params as any).token,
+      projectId: (params as any).projectId,
+      teamId: (params as any).teamId,
     };
   }
 
@@ -84,7 +87,9 @@ function getCredentialsFromParams<Params extends Record<string, unknown>>(
  * Schema to validate the payload of the Vercel OIDC token where we expect
  * to find the `teamId` and `projectId`.
  */
-const schema = z.object({
+export const schema = z.object({
+  exp: z.number().optional().describe("Expiry timestamp (seconds since epoch)"),
+  iat: z.number().optional().describe("Issued at timestamp"),
   owner_id: z.string(),
   project_id: z.string(),
 });

package/src/utils/jwt-expiry.test.ts

@@ -0,0 +1,125 @@
+import { assert, beforeEach, describe, expect, test, vi } from "vitest";
+import { JwtExpiry } from "./jwt-expiry";
+import type { getVercelOidcToken } from "@vercel/oidc";
+
+const { getVercelOidcTokenMock } = vi.hoisted(() => {
+  return {
+    getVercelOidcTokenMock: vi.fn<typeof getVercelOidcToken>(),
+  };
+});
+vi.mock("@vercel/oidc", () => ({
+  getVercelOidcToken: getVercelOidcTokenMock,
+}));
+beforeEach(() => {
+  getVercelOidcTokenMock.mockReset();
+});
+
+describe("JwtExpiry", () => {
+  test("refreshes a token", async () => {
+    const token = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+    });
+    getVercelOidcTokenMock.mockImplementationOnce(async () => "hello world");
+    const expiry = await JwtExpiry.fromToken(token)?.refresh();
+    expect(expiry).toBeInstanceOf(JwtExpiry);
+    expect(expiry?.token).toEqual("hello world");
+  });
+
+  test("isValid returns true for tokens without expiry", () => {
+    // Mock token without exp field (like OIDC tokens without exp)
+    const tokenWithoutExp = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+    });
+    const expiry = JwtExpiry.fromToken(tokenWithoutExp);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false); // No exp field means malformed JWT
+  });
+
+  test("isValid returns true for unexpired tokens", () => {
+    const futureTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+    const tokenValid = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: futureTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenValid);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(true);
+  });
+
+  test("isValid returns false for expired tokens", () => {
+    const pastTime = Math.floor(Date.now() / 1000) - 3600; // 1 hour ago
+    const tokenExpired = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: pastTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenExpired);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false);
+  });
+
+  test("isValid returns false for tokens expiring within buffer time", () => {
+    const soonTime = Math.floor(Date.now() / 1000) + 120; // 2 minutes from now
+    const tokenExpiringSoon = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: soonTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenExpiringSoon);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid(5)).toBe(false); // 5 minute buffer
+  });
+
+  test("isValid returns false for malformed JWT tokens", () => {
+    const expiry = JwtExpiry.fromToken("header.invalid-payload.signature");
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false);
+  });
+
+  test("getExpiryDate returns correct expiry date", () => {
+    const expTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+    const token = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: expTime,
+    });
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toEqual(new Date(expTime * 1000));
+  });
+
+  test("getExpiryDate returns null for tokens without expiry", () => {
+    const token = createMockJWT({ owner_id: "team1", project_id: "proj1" });
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toBeNull();
+  });
+
+  test("getExpiryDate returns null for malformed tokens", () => {
+    const token = "hello.world.hey";
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toBeNull();
+  });
+
+  test("returns null for non-JWT style tokens", () => {
+    expect(JwtExpiry.fromToken("personal-access-token")).toBeNull();
+  });
+});
+
+// Helper function to create mock JWT tokens for testing
+function createMockJWT(payload: any): string {
+  const header = { typ: "JWT", alg: "HS256" };
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString(
+    "base64url",
+  );
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString(
+    "base64url",
+  );
+  const signature = "mock-signature";
+
+  return `${encodedHeader}.${encodedPayload}.${signature}`;
+}

package/src/utils/jwt-expiry.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { decodeBase64Url } from "./decode-base64-url";
+import { schema } from "./get-credentials";
+import { getVercelOidcToken } from "@vercel/oidc";
+import ms from "ms";
+
+/** Time buffer before token expiry to consider it invalid (in milliseconds) */
+const BUFFER_MS = ms("5m");
+
+export class OidcRefreshError extends Error {
+  name = "OidcRefreshError";
+}
+
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+export class JwtExpiry {
+  private expiryTime: number | null; // Unix timestamp in seconds
+  readonly payload?: Readonly<z.infer<typeof schema>>;
+
+  static fromToken(token: string): JwtExpiry | null {
+    if (!isJwtFormat(token)) {
+      return null;
+    } else {
+      return new JwtExpiry(token);
+    }
+  }
+
+  /**
+   * Creates a new JWT expiry checker.
+   *
+   * @param token - The JWT token to parse
+   */
+  constructor(readonly token: string) {
+    try {
+      const tokenContents = token.split(".")[1];
+      this.payload = schema.parse(decodeBase64Url(tokenContents));
+      this.expiryTime = this.payload.exp || null;
+    } catch {
+      // Malformed token - treat as expired to trigger refresh
+      this.expiryTime = 0;
+    }
+  }
+
+  /**
+   * Checks if the JWT token is valid (not expired).
+   * @returns true if token is valid, false if expired or expiring soon
+   */
+  isValid(): boolean {
+    if (this.expiryTime === null) {
+      return false; // No expiry means malformed JWT
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    const buffer = BUFFER_MS / 1000;
+    return now + buffer < this.expiryTime;
+  }
+
+  /**
+   * Gets the expiry date of the JWT token.
+   *
+   * @returns Date object representing when the token expires, or null if no expiry
+   */
+  getExpiryDate(): Date | null {
+    return this.expiryTime ? new Date(this.expiryTime * 1000) : null;
+  }
+
+  /**
+   * Refreshes the JWT token by fetching a new OIDC token.
+   *
+   * @returns Promise resolving to a new JwtExpiry instance with fresh token
+   */
+  async refresh(): Promise<JwtExpiry> {
+    try {
+      const freshToken = await getVercelOidcToken();
+      return new JwtExpiry(freshToken);
+    } catch (cause) {
+      throw new OidcRefreshError("Failed to refresh OIDC token", {
+        cause,
+      });
+    }
+  }
+
+  /**
+   * Refreshes the JWT token if it's expired or expiring soon.
+   */
+  async tryRefresh(): Promise<JwtExpiry | null> {
+    if (this.isValid()) {
+      return null; // Still valid, no need to refresh
+    }
+
+    return this.refresh();
+  }
+}
+
+/**
+ * Checks if a token follows JWT format (has 3 parts separated by dots).
+ *
+ * @param token - The token to check
+ * @returns true if token appears to be a JWT, false otherwise
+ */
+function isJwtFormat(token: string): boolean {
+  return token.split(".").length === 3;
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "0.0.17";
+export const VERSION = "0.0.18";