@hasna/connectors 1.3.13 → 1.3.14

package/connectors/connect-gmail/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/connect-gmail",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Gmail API connector CLI - A TypeScript wrapper for Gmail with OAuth2 authentication",
   "type": "module",
   "bin": {

package/connectors/connect-gmail/src/api/client.ts

@@ -12,11 +12,19 @@ export interface RequestOptions {
   format?: OutputFormat;
 }
 
+export interface GmailClientOptions {
+  /** Custom token provider — if set, used instead of file-based auth */
+  tokenProvider?: () => Promise<string>;
+}
+
 export class GmailClient {
   private accessToken?: string;
   private userId: string = 'me'; // Default to authenticated user
+  private readonly tokenProvider?: () => Promise<string>;
 
-  constructor() {}
+  constructor(options?: GmailClientOptions) {
+    this.tokenProvider = options?.tokenProvider;
+  }
 
   setUserId(userId: string): void {
     this.userId = userId;
@@ -43,8 +51,10 @@ export class GmailClient {
   async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
     const { method = 'GET', params, body, headers = {} } = options;
 
-    // Get fresh access token (handles refresh automatically)
-    const accessToken = await getValidAccessToken();
+    // Get fresh access token — use injected tokenProvider if available, otherwise file-based auth
+    const accessToken = this.tokenProvider
+      ? await this.tokenProvider()
+      : await getValidAccessToken();
 
     const url = this.buildUrl(path, params);
 

package/connectors/connect-gmail/src/api/index.ts

@@ -8,6 +8,17 @@ import { FiltersApi } from './filters';
 import { AttachmentsApi } from './attachments';
 import { ExportApi } from './export';
 import { BulkApi } from './bulk';
+import { refreshTokens } from '../utils/auth';
+
+/** Tokens passed to Gmail.createWithTokens() */
+export interface GmailTokens {
+  accessToken: string;
+  refreshToken: string;
+  clientId: string;
+  clientSecret: string;
+  /** Unix timestamp (ms) when accessToken expires. If omitted, token is always refreshed. */
+  expiresAt?: number;
+}
 
 export class Gmail {
   private readonly client: GmailClient;
@@ -23,8 +34,8 @@ export class Gmail {
   public readonly export: ExportApi;
   public readonly bulk: BulkApi;
 
-  constructor() {
-    this.client = new GmailClient();
+  constructor(client?: GmailClient) {
+    this.client = client ?? new GmailClient();
     this.messages = new MessagesApi(this.client);
     this.labels = new LabelsApi(this.client);
     this.threads = new ThreadsApi(this.client);
@@ -37,12 +48,96 @@ export class Gmail {
   }
 
   /**
-   * Create a Gmail client - tokens are loaded automatically from config
+   * Create a Gmail client — tokens are loaded automatically from config
    */
   static create(): Gmail {
     return new Gmail();
   }
 
+  /**
+   * Create a Gmail client from environment variables.
+   *
+   * Supports two modes:
+   * - Full OAuth: GMAIL_REFRESH_TOKEN + GMAIL_CLIENT_ID + GMAIL_CLIENT_SECRET
+   *   (optionally GMAIL_ACCESS_TOKEN + GMAIL_TOKEN_EXPIRES_AT to skip initial refresh)
+   * - Static token: GMAIL_ACCESS_TOKEN only (no auto-refresh)
+   */
+  static fromEnv(): Gmail {
+    const accessToken = process.env.GMAIL_ACCESS_TOKEN;
+    const refreshToken = process.env.GMAIL_REFRESH_TOKEN;
+    const clientId = process.env.GMAIL_CLIENT_ID;
+    const clientSecret = process.env.GMAIL_CLIENT_SECRET;
+    const expiresAt = process.env.GMAIL_TOKEN_EXPIRES_AT
+      ? parseInt(process.env.GMAIL_TOKEN_EXPIRES_AT, 10)
+      : undefined;
+
+    if (refreshToken && clientId && clientSecret) {
+      return Gmail.createWithTokens({
+        accessToken: accessToken ?? '',
+        refreshToken,
+        clientId,
+        clientSecret,
+        // Force immediate refresh if no access token was provided
+        expiresAt: accessToken ? expiresAt : 0,
+      });
+    }
+
+    if (accessToken) {
+      // Static token only — no auto-refresh
+      const client = new GmailClient({ tokenProvider: async () => accessToken });
+      return new Gmail(client);
+    }
+
+    throw new Error(
+      'Missing Gmail env vars. Provide GMAIL_ACCESS_TOKEN, ' +
+      'or GMAIL_REFRESH_TOKEN + GMAIL_CLIENT_ID + GMAIL_CLIENT_SECRET',
+    );
+  }
+
+  /**
+   * Create a Gmail client using explicit tokens instead of file-based auth.
+   * Automatically refreshes the access token when expired and notifies via onRefresh.
+   *
+   * @param tokens - Initial token set (accessToken, refreshToken, clientId, clientSecret, expiresAt?)
+   * @param onRefresh - Called whenever tokens are refreshed so callers can persist the new tokens
+   */
+  static createWithTokens(
+    tokens: GmailTokens,
+    onRefresh?: (newTokens: GmailTokens) => void,
+  ): Gmail {
+    // Mutable state for the closure — updated on each refresh
+    let current = { ...tokens };
+
+    const tokenProvider = async (): Promise<string> => {
+      const isExpired =
+        current.expiresAt === undefined ||
+        Date.now() >= current.expiresAt - 5 * 60 * 1000;
+
+      if (isExpired) {
+        const refreshed = await refreshTokens(
+          current.clientId,
+          current.clientSecret,
+          current.refreshToken,
+        );
+
+        current = {
+          accessToken: refreshed.accessToken,
+          refreshToken: refreshed.refreshToken,
+          clientId: current.clientId,
+          clientSecret: current.clientSecret,
+          expiresAt: refreshed.expiresAt,
+        };
+
+        onRefresh?.(current);
+      }
+
+      return current.accessToken;
+    };
+
+    const client = new GmailClient({ tokenProvider });
+    return new Gmail(client);
+  }
+
   /**
    * Get the underlying client for direct API access
    */

package/connectors/connect-gmail/src/index.ts

@@ -2,6 +2,7 @@
 // A TypeScript wrapper for Gmail with OAuth2 authentication
 
 export { Gmail } from './api';
+export type { GmailTokens } from './api';
 export * from './types';
 
 // Re-export individual API classes for advanced usage
@@ -18,9 +19,12 @@ export {
   getAuthUrl,
   startCallbackServer,
   refreshAccessToken,
+  refreshTokens,
   getValidAccessToken,
 } from './utils/auth';
 
+export type { GmailClientOptions } from './api/client';
+
 // Export config utilities
 export {
   isAuthenticated,

package/connectors/connect-gmail/src/utils/auth.ts

@@ -101,21 +101,15 @@ export async function exchangeCodeForTokens(code: string): Promise<OAuth2Tokens>
 }
 
 /**
- * Refresh the access token using the refresh token
+ * Pure function to refresh an OAuth2 access token using provided credentials.
+ * Does NOT touch the file system — no saveTokens, no loadTokens.
  */
-export async function refreshAccessToken(): Promise<OAuth2Tokens> {
-  const clientId = getClientId();
-  const clientSecret = getClientSecret();
-  const currentTokens = loadTokens();
-
-  if (!clientId || !clientSecret) {
-    throw new Error('OAuth credentials not configured');
-  }
-
-  if (!currentTokens?.refreshToken) {
-    throw new Error('No refresh token available. Please login again.');
-  }
-
+export async function refreshTokens(
+  clientId: string,
+  clientSecret: string,
+  refreshToken: string,
+  currentScope?: string,
+): Promise<OAuth2Tokens> {
   const response = await fetch(GOOGLE_TOKEN_URL, {
     method: 'POST',
     headers: {
@@ -124,7 +118,7 @@ export async function refreshAccessToken(): Promise<OAuth2Tokens> {
     body: new URLSearchParams({
       client_id: clientId,
       client_secret: clientSecret,
-      refresh_token: currentTokens.refreshToken,
+      refresh_token: refreshToken,
       grant_type: 'refresh_token',
     }),
   });
@@ -145,14 +139,33 @@ export async function refreshAccessToken(): Promise<OAuth2Tokens> {
 
   const data = await response.json();
 
-  const tokens: OAuth2Tokens = {
+  return {
     accessToken: data.access_token,
-    refreshToken: currentTokens.refreshToken, // Keep the original refresh token
+    refreshToken, // Keep the original refresh token
     expiresAt: Date.now() + data.expires_in * 1000,
     tokenType: data.token_type,
-    scope: data.scope || currentTokens.scope,
+    scope: data.scope || currentScope || '',
   };
+}
+
+/**
+ * Refresh the access token using the refresh token (file-based auth).
+ * Thin wrapper around refreshTokens() that reads/writes config files.
+ */
+export async function refreshAccessToken(): Promise<OAuth2Tokens> {
+  const clientId = getClientId();
+  const clientSecret = getClientSecret();
+  const currentTokens = loadTokens();
+
+  if (!clientId || !clientSecret) {
+    throw new Error('OAuth credentials not configured');
+  }
+
+  if (!currentTokens?.refreshToken) {
+    throw new Error('No refresh token available. Please login again.');
+  }
 
+  const tokens = await refreshTokens(clientId, clientSecret, currentTokens.refreshToken, currentTokens.scope);
   saveTokens(tokens);
   return tokens;
 }

package/connectors/connect-stripe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/connect-stripe",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Stripe API connector - A TypeScript CLI for interacting with the Stripe API with multi-profile support",
   "type": "module",
   "bin": {

package/connectors/connect-stripe/src/api/index.ts

@@ -68,8 +68,15 @@ export class Connector {
   }
 
   /**
-   * Create a client from environment variables
-   * Looks for STRIPE_API_KEY and optionally STRIPE_API_SECRET
+   * Create a client from an API key directly.
+   */
+  static fromApiKey(apiKey: string, options?: Omit<ConnectorConfig, 'apiKey'>): Connector {
+    return new Connector({ apiKey, ...options });
+  }
+
+  /**
+   * Create a client from environment variables.
+   * Looks for STRIPE_API_KEY and optionally STRIPE_API_SECRET.
    */
   static fromEnv(): Connector {
     const apiKey = process.env.STRIPE_API_KEY;

package/connectors/connect-stripe/src/index.ts

@@ -1,7 +1,7 @@
 // Stripe Connector API
 // A TypeScript wrapper for the Stripe API
 
-export { Connector } from './api';
+export { Connector, Connector as Stripe } from './api';
 export * from './types';
 
 // Re-export individual API classes for advanced usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/connectors",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "description": "Open source connector library - Install API connectors with a single command",
   "type": "module",
   "bin": {