@vunexa/lixa 0.1.6-alpha.3 → 0.1.6-alpha.4

package/README.md

@@ -187,15 +187,16 @@ app.get("/connect/github/callback", async (req, res) => {
   res.redirect("/dashboard");
 });
 
-// 3. Query Connected Resource Access Token
+// 3. Query Connected Resource Access Token (Auto-Refreshes Expired Tokens)
 app.get("/api/github/repos", async (req, res) => {
+  // Queries by active session OR user ID, auto-refreshing expired access tokens
   const resource = await lixa.getConnectedResource(req.cookies.session_id, "github");
 
   if (!resource) {
     return res.status(403).json({ error: "GitHub resource not connected" });
   }
 
-  // Call GitHub API with resource access token
+  // Call GitHub API with active resource access token
   const response = await fetch("https://api.github.com/user/repos", {
     headers: { Authorization: `Bearer ${resource.accessToken}` },
   });
@@ -204,7 +205,10 @@ app.get("/api/github/repos", async (req, res) => {
   res.json(repos);
 });
 
-// 4. Disconnect Resource Provider
+// 4. Query Resource Directly by User ID (e.g. inside background cron jobs or webhooks)
+const githubResource = await lixa.getUserResource(userId, "github");
+
+// 5. Disconnect Resource Provider
 app.delete("/connect/github", async (req, res) => {
   await lixa.disconnectResource(req.cookies.session_id, "github");
   res.json({ success: true });
@@ -503,7 +507,113 @@ export const lixa = new Lixa({
         "connectedAt": 1771657300000
       }
     }
+  ---
+
+## Custom Resource Storage Implementation (`ResourceStorage`)
+
+While `SessionStorage` manages short-lived user authentication sessions (indexed by `sessionId`), **`ResourceStorage`** manages long-lived third-party API tokens (**AuthZ**) bound directly to a **User ID** (or Email). This ensures that third-party credentials (such as GitHub Repositories or Google Drive) persist across session expirations and logouts.
+
+### `ResourceStorage` Interface
+
+```typescript
+export interface ResourceStorage {
+  saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void>;
+  getResource(userId: string, provider: string): Promise<ConnectedResource | null>;
+  getUserResources(userId: string): Promise<Record<string, ConnectedResource>>;
+  deleteResource(userId: string, provider: string): Promise<void>;
+}
+```
+
+### 1. SQLite Resource Storage (`better-sqlite3`)
+
+#### Table Schema (SQL DDL)
+
+```sql
+CREATE TABLE IF NOT EXISTS user_resources (
+  user_id TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  data TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (user_id, provider)
+);
+```
+
+#### TypeScript Implementation
+
+```typescript
+import Database from "better-sqlite3";
+import { Lixa, type ResourceStorage, type ConnectedResource } from "@vunexa/lixa";
+
+export class SqliteResourceStorage implements ResourceStorage {
+  private db = new Database("lixa_resources.db");
+
+  constructor() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS user_resources (
+        user_id TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        data TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (user_id, provider)
+      );
+    `);
   }
+
+  async saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void> {
+    const stmt = this.db.prepare(`
+      INSERT INTO user_resources (user_id, provider, data, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(user_id, provider) DO UPDATE SET
+        data = excluded.data,
+        updated_at = excluded.updated_at
+    `);
+    stmt.run(userId, provider.toLowerCase(), JSON.stringify(resource), Date.now());
+  }
+
+  async getResource(userId: string, provider: string): Promise<ConnectedResource | null> {
+    const stmt = this.db.prepare(`SELECT data FROM user_resources WHERE user_id = ? AND provider = ?`);
+    const row = stmt.get(userId, provider.toLowerCase()) as { data: string } | undefined;
+    return row ? (JSON.parse(row.data) as ConnectedResource) : null;
+  }
+
+  async getUserResources(userId: string): Promise<Record<string, ConnectedResource>> {
+    const stmt = this.db.prepare(`SELECT provider, data FROM user_resources WHERE user_id = ?`);
+    const rows = stmt.all(userId) as Array<{ provider: string; data: string }>;
+    const result: Record<string, ConnectedResource> = {};
+    for (const r of rows) {
+      result[r.provider] = JSON.parse(r.data);
+    }
+    return result;
+  }
+
+  async deleteResource(userId: string, provider: string): Promise<void> {
+    const stmt = this.db.prepare(`DELETE FROM user_resources WHERE user_id = ? AND provider = ?`);
+    stmt.run(userId, provider.toLowerCase());
+  }
+}
+
+// Pass to Lixa instance via resourceHandler
+export const lixa = new Lixa({
+  resourceHandler: {
+    resourceStorage: new SqliteResourceStorage(),
+  },
+  providers: { /* ... */ },
+});
+```
+
+### 2. Querying Connected Resources Directly by User ID
+
+`ResourceStorage` enables background workers, cron jobs, and webhooks to access third-party API credentials by `userId` without an active HTTP session:
+
+```typescript
+// Background worker querying user's GitHub Repos token
+const githubResource = await lixa.getUserResource(user.id, "github");
+
+if (githubResource) {
+  // Lixa auto-refreshes expired access tokens transparently!
+  const response = await fetch("https://api.github.com/user/repos", {
+    headers: { Authorization: `Bearer ${githubResource.accessToken}` },
+  });
 }
 ```
 

package/README.template.md

@@ -277,15 +277,16 @@ app.get("/connect/github/callback", async (req, res) => {
   res.redirect("/dashboard");
 });
 
-// 3. Query Connected Resource Access Token
+// 3. Query Connected Resource Access Token (Auto-Refreshes Expired Tokens)
 app.get("/api/github/repos", async (req, res) => {
+  // Queries by active session OR user ID, auto-refreshing expired access tokens
   const resource = await lixa.getConnectedResource(req.cookies.session_id, "github");
 
   if (!resource) {
     return res.status(403).json({ error: "GitHub resource not connected" });
   }
 
-  // Call GitHub API with resource access token
+  // Call GitHub API with active resource access token
   const response = await fetch("https://api.github.com/user/repos", {
     headers: { Authorization: `Bearer ${resource.accessToken}` },
   });
@@ -294,7 +295,10 @@ app.get("/api/github/repos", async (req, res) => {
   res.json(repos);
 });
 
-// 4. Disconnect Resource Provider
+// 4. Query Resource Directly by User ID (e.g. inside background cron jobs or webhooks)
+const githubResource = await lixa.getUserResource(userId, "github");
+
+// 5. Disconnect Resource Provider
 app.delete("/connect/github", async (req, res) => {
   await lixa.disconnectResource(req.cookies.session_id, "github");
   res.json({ success: true });
@@ -593,7 +597,113 @@ export const lixa = new Lixa({
         "connectedAt": 1771657300000
       }
     }
+  ---
+
+## Custom Resource Storage Implementation (`ResourceStorage`)
+
+While `SessionStorage` manages short-lived user authentication sessions (indexed by `sessionId`), **`ResourceStorage`** manages long-lived third-party API tokens (**AuthZ**) bound directly to a **User ID** (or Email). This ensures that third-party credentials (such as GitHub Repositories or Google Drive) persist across session expirations and logouts.
+
+### `ResourceStorage` Interface
+
+```typescript
+export interface ResourceStorage {
+  saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void>;
+  getResource(userId: string, provider: string): Promise<ConnectedResource | null>;
+  getUserResources(userId: string): Promise<Record<string, ConnectedResource>>;
+  deleteResource(userId: string, provider: string): Promise<void>;
+}
+```
+
+### 1. SQLite Resource Storage (`better-sqlite3`)
+
+#### Table Schema (SQL DDL)
+
+```sql
+CREATE TABLE IF NOT EXISTS user_resources (
+  user_id TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  data TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (user_id, provider)
+);
+```
+
+#### TypeScript Implementation
+
+```typescript
+import Database from "better-sqlite3";
+import { Lixa, type ResourceStorage, type ConnectedResource } from "@vunexa/lixa";
+
+export class SqliteResourceStorage implements ResourceStorage {
+  private db = new Database("lixa_resources.db");
+
+  constructor() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS user_resources (
+        user_id TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        data TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (user_id, provider)
+      );
+    `);
   }
+
+  async saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void> {
+    const stmt = this.db.prepare(`
+      INSERT INTO user_resources (user_id, provider, data, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(user_id, provider) DO UPDATE SET
+        data = excluded.data,
+        updated_at = excluded.updated_at
+    `);
+    stmt.run(userId, provider.toLowerCase(), JSON.stringify(resource), Date.now());
+  }
+
+  async getResource(userId: string, provider: string): Promise<ConnectedResource | null> {
+    const stmt = this.db.prepare(`SELECT data FROM user_resources WHERE user_id = ? AND provider = ?`);
+    const row = stmt.get(userId, provider.toLowerCase()) as { data: string } | undefined;
+    return row ? (JSON.parse(row.data) as ConnectedResource) : null;
+  }
+
+  async getUserResources(userId: string): Promise<Record<string, ConnectedResource>> {
+    const stmt = this.db.prepare(`SELECT provider, data FROM user_resources WHERE user_id = ?`);
+    const rows = stmt.all(userId) as Array<{ provider: string; data: string }>;
+    const result: Record<string, ConnectedResource> = {};
+    for (const r of rows) {
+      result[r.provider] = JSON.parse(r.data);
+    }
+    return result;
+  }
+
+  async deleteResource(userId: string, provider: string): Promise<void> {
+    const stmt = this.db.prepare(`DELETE FROM user_resources WHERE user_id = ? AND provider = ?`);
+    stmt.run(userId, provider.toLowerCase());
+  }
+}
+
+// Pass to Lixa instance via resourceHandler
+export const lixa = new Lixa({
+  resourceHandler: {
+    resourceStorage: new SqliteResourceStorage(),
+  },
+  providers: { /* ... */ },
+});
+```
+
+### 2. Querying Connected Resources Directly by User ID
+
+`ResourceStorage` enables background workers, cron jobs, and webhooks to access third-party API credentials by `userId` without an active HTTP session:
+
+```typescript
+// Background worker querying user's GitHub Repos token
+const githubResource = await lixa.getUserResource(user.id, "github");
+
+if (githubResource) {
+  // Lixa auto-refreshes expired access tokens transparently!
+  const response = await fetch("https://api.github.com/user/repos", {
+    headers: { Authorization: `Bearer ${githubResource.accessToken}` },
+  });
 }
 ```
 

package/dist/dao/types.d.ts

@@ -220,6 +220,53 @@ export interface SessionStorage {
         session: T;
     } | null>;
 }
+/**
+ * Resource storage operations interface.
+ *
+ * @remarks
+ * Manages long-lived third-party resource provider tokens (AuthZ) bound to a user account
+ * (User ID or Email), independent of short-lived user sessions.
+ *
+ * @public
+ */
+export interface ResourceStorage {
+    /**
+     * Saves a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name (e.g. 'github', 'google')
+     * @param resource - Connected resource details including access & refresh tokens
+     */
+    saveResource(userId: string, provider: string, resource: import("../models/session").ConnectedResource): Promise<void>;
+    /**
+     * Retrieves a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name
+     */
+    getResource(userId: string, provider: string): Promise<import("../models/session").ConnectedResource | null>;
+    /**
+     * Retrieves all connected resources for a user.
+     *
+     * @param userId - Unique user identifier or email
+     */
+    getUserResources(userId: string): Promise<Record<string, import("../models/session").ConnectedResource>>;
+    /**
+     * Deletes a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name
+     */
+    deleteResource(userId: string, provider: string): Promise<void>;
+}
+/**
+ * Resource handler configuration.
+ *
+ * @public
+ */
+export interface ResourceHandler {
+    resourceStorage?: ResourceStorage;
+}
 /**
  * Session handler for OAuth authentication.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAE9E;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvG;;;;;OAKG;IACH,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEpE;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,eAAe,CAAC,CAAC,CAAC,SAAS,OAAO,EAChC,SAAS,EAAE,OAAO,mBAAmB,EAAE,kBAAkB,EACzD,gBAAgB,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,GAC7D,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;OAKG;IACH,eAAe,CAAC,CAAC,CAAC,SAAS,OAAO,EAChC,SAAS,EAAE,OAAO,mBAAmB,EAAE,kBAAkB,EACzD,gBAAgB,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,GAC7D,OAAO,CAAC,CAAC,CAAC,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"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"}

package/dist/export-types/index.d.ts

@@ -141,6 +141,8 @@ export declare interface ConnectedResource {
     accessToken: string;
     /** Optional refresh token for offline resource access */
     refreshToken?: string | undefined;
+    /** Unix timestamp in milliseconds when the resource access token expires */
+    expiresAt?: number | undefined;
     /** Resource scopes granted by the user */
     scopes: string[];
     /** Full raw token response from provider */
@@ -437,6 +439,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
     private config;
     private stateHandler;
     private sessionHandler;
+    private resourceHandler;
     private debug;
     /**
      * Creates a new Lixa instance with the provided configuration.
@@ -749,6 +752,12 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * @param params - Object containing sessionId, provider, code, state, and requested scopes
      * @returns Updated Session containing stored resource tokens under session.resources[provider]
      */
+    private static userResourceStore;
+    static LOCAL_RESOURCE_HANDLER: ResourceHandler;
+    private getUserKeyFromSession;
+    /**
+     * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
+     */
     handleResourceCallback(params: {
         sessionId: string;
         provider: ConfiguredProviderKey<TConfig> | string;
@@ -757,17 +766,41 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
         scopes?: string[];
     }): Promise<Session>;
     /**
-     * Retrieves a connected resource provider token for an active session.
+     * Retrieves a connected resource for a specific User ID / Email directly (independent of session IDs).
+     * Automatically refreshes expired access tokens if a refresh token is present.
+     *
+     * @param userIdOrEmail - User identifier or email
+     * @param provider - Resource provider identifier (e.g. 'github', 'google')
+     */
+    getUserResource(userIdOrEmail: string, provider: string): Promise<ConnectedResource | null>;
+    /**
+     * Retrieves all connected resources for a specific User ID / Email.
+     */
+    getUserResources(userIdOrEmail: string): Promise<Record<string, ConnectedResource>>;
+    /**
+     * Retrieves a connected resource provider token for an active session, auto-refreshing expired tokens if possible.
      *
      * @param sessionId - Active session ID
-     * @param provider - Provider identifier (e.g. 'github')
+     * @param provider - Provider identifier (e.g. 'github', 'google')
      */
     getConnectedResource(sessionId: string, provider: string): Promise<ConnectedResource | null>;
     /**
-     * Disconnects a resource provider from an active session.
+     * Refreshes a user's resource access token using its refresh token.
      *
-     * @param sessionId - Active session ID
-     * @param provider - Provider identifier to disconnect
+     * @param userIdOrEmail - User identifier or email
+     * @param provider - Provider identifier (e.g. 'google', 'github')
+     */
+    refreshUserResourceToken(userIdOrEmail: string, provider: string, existingResource?: ConnectedResource): Promise<ConnectedResource>;
+    /**
+     * Refreshes a connected resource access token for an active session.
+     */
+    refreshResourceToken(sessionId: string, provider: string): Promise<ConnectedResource>;
+    /**
+     * Disconnects a resource provider for a specific User ID / Email.
+     */
+    disconnectUserResource(userIdOrEmail: string, provider: string): Promise<boolean>;
+    /**
+     * Disconnects a resource provider from an active session and user account.
      */
     disconnectResource(sessionId: string, provider: string): Promise<boolean>;
     fetchSessionInfo(sessionId: string): Promise<Session | null>;
@@ -815,6 +848,14 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
      * @see {@link SessionHandler}
      */
     sessionHandler?: SessionHandler;
+    /**
+     * Optional custom resource handler.
+     * Handles storage and management of long-lived third-party resource provider tokens (AuthZ)
+     * bound directly to user accounts (User ID or Email), independent of transient session IDs.
+     *
+     * @see {@link ResourceHandler}
+     */
+    resourceHandler?: ResourceHandler;
     /**
      * Enable debug logging.
      * When enabled, outputs structured logs for initialization, auth flow, and errors.
@@ -945,6 +986,55 @@ export declare interface ProviderMetadata {
     };
 }
 
+/**
+ * Resource handler configuration.
+ *
+ * @public
+ */
+export declare interface ResourceHandler {
+    resourceStorage?: ResourceStorage;
+}
+
+/**
+ * Resource storage operations interface.
+ *
+ * @remarks
+ * Manages long-lived third-party resource provider tokens (AuthZ) bound to a user account
+ * (User ID or Email), independent of short-lived user sessions.
+ *
+ * @public
+ */
+export declare interface ResourceStorage {
+    /**
+     * Saves a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name (e.g. 'github', 'google')
+     * @param resource - Connected resource details including access & refresh tokens
+     */
+    saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void>;
+    /**
+     * Retrieves a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name
+     */
+    getResource(userId: string, provider: string): Promise<ConnectedResource | null>;
+    /**
+     * Retrieves all connected resources for a user.
+     *
+     * @param userId - Unique user identifier or email
+     */
+    getUserResources(userId: string): Promise<Record<string, ConnectedResource>>;
+    /**
+     * Deletes a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name
+     */
+    deleteResource(userId: string, provider: string): Promise<void>;
+}
+
 /**
  * Helper type to create a configuration with only registered providers.
  * Use this with Lixa.createConfig() for type safety.