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

package/README.md

@@ -363,14 +363,6 @@ export const lixa = new Lixa({
       "accessToken": "gho_8f7b2a9e1c3...",
       "linkedAt": 1771657250000
     }
-  },
-  "resources": {
-    "github": {
-      "provider": "github",
-      "accessToken": "gho_resource_repo_9a8b7c...",
-      "scopes": ["repo", "read:org"],
-      "connectedAt": 1771657300000
-    }
   }
 }
 ```
@@ -498,16 +490,12 @@ export const lixa = new Lixa({
         "accessToken": "gho_8f7b2a9e1c3...",
         "linkedAt": 1771657250000
       }
-    },
-    "resources": {
-      "github": {
-        "provider": "github",
-        "accessToken": "gho_resource_repo_9a8b7c...",
-        "scopes": ["repo", "read:org"],
-        "connectedAt": 1771657300000
-      }
     }
-  ---
+  }
+}
+```
+
+---
 
 ## Custom Resource Storage Implementation (`ResourceStorage`)
 
@@ -601,7 +589,168 @@ export const lixa = new Lixa({
 });
 ```
 
-### 2. Querying Connected Resources Directly by User ID
+#### Saved JSON Records Example in SQLite (`user_resources` Table)
+
+**Row 1 (GitHub Repositories)**:
+```json
+{
+  "user_id": "1049281048",
+  "provider": "github",
+  "data": {
+    "accessToken": "gho_resource_repo_9a8b7c...",
+    "refreshToken": "ghr_refresh_token_123...",
+    "scopes": ["repo", "read:org"],
+    "expiresAt": 1771743600000,
+    "connectedAt": 1771657300000
+  }
+}
+```
+
+**Row 2 (Google Drive)**:
+```json
+{
+  "user_id": "1049281048",
+  "provider": "google",
+  "data": {
+    "accessToken": "ya29.drive_resource_token_456...",
+    "refreshToken": "1//09abc_google_refresh_token...",
+    "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
+    "expiresAt": 1771660800000,
+    "connectedAt": 1771657400000
+  }
+}
+```
+
+---
+
+### 2. AWS DynamoDB Resource Storage (`@aws-sdk/lib-dynamodb`)
+
+For serverless AWS deployments storing user API credentials in DynamoDB:
+
+#### Table Configuration
+
+- **Table Name**: `LixaUserResources`
+- **Partition Key (PK)**: `userId` (String)
+- **Sort Key (SK)**: `provider` (String)
+
+#### TypeScript Implementation
+
+```typescript
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, PutCommand, GetCommand, DeleteCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
+import { Lixa, type ResourceStorage, type ConnectedResource } from "@vunexa/lixa";
+
+export class DynamoDbResourceStorage implements ResourceStorage {
+  private docClient: DynamoDBDocumentClient;
+  private tableName = "LixaUserResources";
+
+  constructor() {
+    const client = new DynamoDBClient({ region: process.env.AWS_REGION || "us-east-1" });
+    this.docClient = DynamoDBDocumentClient.from(client);
+  }
+
+  async saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void> {
+    await this.docClient.send(
+      new PutCommand({
+        TableName: this.tableName,
+        Item: {
+          userId,
+          provider: provider.toLowerCase(),
+          resourceData: resource,
+          updatedAt: Date.now(),
+        },
+      })
+    );
+  }
+
+  async getResource(userId: string, provider: string): Promise<ConnectedResource | null> {
+    const res = await this.docClient.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: {
+          userId,
+          provider: provider.toLowerCase(),
+        },
+      })
+    );
+
+    return res.Item ? (res.Item.resourceData as ConnectedResource) : null;
+  }
+
+  async getUserResources(userId: string): Promise<Record<string, ConnectedResource>> {
+    const res = await this.docClient.send(
+      new QueryCommand({
+        TableName: this.tableName,
+        KeyConditionExpression: "userId = :userId",
+        ExpressionAttributeValues: { ":userId": userId },
+      })
+    );
+
+    const result: Record<string, ConnectedResource> = {};
+    if (res.Items) {
+      for (const item of res.Items) {
+        result[item.provider] = item.resourceData as ConnectedResource;
+      }
+    }
+    return result;
+  }
+
+  async deleteResource(userId: string, provider: string): Promise<void> {
+    await this.docClient.send(
+      new DeleteCommand({
+        TableName: this.tableName,
+        Key: {
+          userId,
+          provider: provider.toLowerCase(),
+        },
+      })
+    );
+  }
+}
+
+// Pass to Lixa instance via resourceHandler
+export const lixa = new Lixa({
+  resourceHandler: {
+    resourceStorage: new DynamoDbResourceStorage(),
+  },
+  providers: { /* ... */ },
+});
+```
+
+#### Saved DynamoDB Resource Items Example (`LixaUserResources` Table)
+
+```json
+[
+  {
+    "userId": "1049281048",
+    "provider": "github",
+    "updatedAt": 1771657300000,
+    "resourceData": {
+      "accessToken": "gho_resource_repo_9a8b7c...",
+      "refreshToken": "ghr_refresh_token_123...",
+      "scopes": ["repo", "read:org"],
+      "expiresAt": 1771743600000,
+      "connectedAt": 1771657300000
+    }
+  },
+  {
+    "userId": "1049281048",
+    "provider": "google",
+    "updatedAt": 1771657400000,
+    "resourceData": {
+      "accessToken": "ya29.drive_resource_token_456...",
+      "refreshToken": "1//09abc_google_refresh_token...",
+      "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
+      "expiresAt": 1771660800000,
+      "connectedAt": 1771657400000
+    }
+  }
+]
+```
+
+---
+
+### 3. 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:
 

package/README.template.md

@@ -453,14 +453,6 @@ export const lixa = new Lixa({
       "accessToken": "gho_8f7b2a9e1c3...",
       "linkedAt": 1771657250000
     }
-  },
-  "resources": {
-    "github": {
-      "provider": "github",
-      "accessToken": "gho_resource_repo_9a8b7c...",
-      "scopes": ["repo", "read:org"],
-      "connectedAt": 1771657300000
-    }
   }
 }
 ```
@@ -588,16 +580,12 @@ export const lixa = new Lixa({
         "accessToken": "gho_8f7b2a9e1c3...",
         "linkedAt": 1771657250000
       }
-    },
-    "resources": {
-      "github": {
-        "provider": "github",
-        "accessToken": "gho_resource_repo_9a8b7c...",
-        "scopes": ["repo", "read:org"],
-        "connectedAt": 1771657300000
-      }
     }
-  ---
+  }
+}
+```
+
+---
 
 ## Custom Resource Storage Implementation (`ResourceStorage`)
 
@@ -691,7 +679,168 @@ export const lixa = new Lixa({
 });
 ```
 
-### 2. Querying Connected Resources Directly by User ID
+#### Saved JSON Records Example in SQLite (`user_resources` Table)
+
+**Row 1 (GitHub Repositories)**:
+```json
+{
+  "user_id": "1049281048",
+  "provider": "github",
+  "data": {
+    "accessToken": "gho_resource_repo_9a8b7c...",
+    "refreshToken": "ghr_refresh_token_123...",
+    "scopes": ["repo", "read:org"],
+    "expiresAt": 1771743600000,
+    "connectedAt": 1771657300000
+  }
+}
+```
+
+**Row 2 (Google Drive)**:
+```json
+{
+  "user_id": "1049281048",
+  "provider": "google",
+  "data": {
+    "accessToken": "ya29.drive_resource_token_456...",
+    "refreshToken": "1//09abc_google_refresh_token...",
+    "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
+    "expiresAt": 1771660800000,
+    "connectedAt": 1771657400000
+  }
+}
+```
+
+---
+
+### 2. AWS DynamoDB Resource Storage (`@aws-sdk/lib-dynamodb`)
+
+For serverless AWS deployments storing user API credentials in DynamoDB:
+
+#### Table Configuration
+
+- **Table Name**: `LixaUserResources`
+- **Partition Key (PK)**: `userId` (String)
+- **Sort Key (SK)**: `provider` (String)
+
+#### TypeScript Implementation
+
+```typescript
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, PutCommand, GetCommand, DeleteCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
+import { Lixa, type ResourceStorage, type ConnectedResource } from "@vunexa/lixa";
+
+export class DynamoDbResourceStorage implements ResourceStorage {
+  private docClient: DynamoDBDocumentClient;
+  private tableName = "LixaUserResources";
+
+  constructor() {
+    const client = new DynamoDBClient({ region: process.env.AWS_REGION || "us-east-1" });
+    this.docClient = DynamoDBDocumentClient.from(client);
+  }
+
+  async saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void> {
+    await this.docClient.send(
+      new PutCommand({
+        TableName: this.tableName,
+        Item: {
+          userId,
+          provider: provider.toLowerCase(),
+          resourceData: resource,
+          updatedAt: Date.now(),
+        },
+      })
+    );
+  }
+
+  async getResource(userId: string, provider: string): Promise<ConnectedResource | null> {
+    const res = await this.docClient.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: {
+          userId,
+          provider: provider.toLowerCase(),
+        },
+      })
+    );
+
+    return res.Item ? (res.Item.resourceData as ConnectedResource) : null;
+  }
+
+  async getUserResources(userId: string): Promise<Record<string, ConnectedResource>> {
+    const res = await this.docClient.send(
+      new QueryCommand({
+        TableName: this.tableName,
+        KeyConditionExpression: "userId = :userId",
+        ExpressionAttributeValues: { ":userId": userId },
+      })
+    );
+
+    const result: Record<string, ConnectedResource> = {};
+    if (res.Items) {
+      for (const item of res.Items) {
+        result[item.provider] = item.resourceData as ConnectedResource;
+      }
+    }
+    return result;
+  }
+
+  async deleteResource(userId: string, provider: string): Promise<void> {
+    await this.docClient.send(
+      new DeleteCommand({
+        TableName: this.tableName,
+        Key: {
+          userId,
+          provider: provider.toLowerCase(),
+        },
+      })
+    );
+  }
+}
+
+// Pass to Lixa instance via resourceHandler
+export const lixa = new Lixa({
+  resourceHandler: {
+    resourceStorage: new DynamoDbResourceStorage(),
+  },
+  providers: { /* ... */ },
+});
+```
+
+#### Saved DynamoDB Resource Items Example (`LixaUserResources` Table)
+
+```json
+[
+  {
+    "userId": "1049281048",
+    "provider": "github",
+    "updatedAt": 1771657300000,
+    "resourceData": {
+      "accessToken": "gho_resource_repo_9a8b7c...",
+      "refreshToken": "ghr_refresh_token_123...",
+      "scopes": ["repo", "read:org"],
+      "expiresAt": 1771743600000,
+      "connectedAt": 1771657300000
+    }
+  },
+  {
+    "userId": "1049281048",
+    "provider": "google",
+    "updatedAt": 1771657400000,
+    "resourceData": {
+      "accessToken": "ya29.drive_resource_token_456...",
+      "refreshToken": "1//09abc_google_refresh_token...",
+      "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
+      "expiresAt": 1771660800000,
+      "connectedAt": 1771657400000
+    }
+  }
+]
+```
+
+---
+
+### 3. 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vunexa/lixa",
-  "version": "0.1.6-alpha.4",
+  "version": "0.1.6-alpha.7",
   "description": "Lixa is a flexible, provider-agnostic OAuth and OpenID Connect (OIDC) client library that simplifies multi-provider authentication flows. It supports seamless integration with providers like Google and GitHub, offers extensible session management, and enables dynamic provider resolution based on callback URLs.",
   "keywords": [
     "oauth",