Merge branch 'main' of github.com:devforth/adminforth

Author: ivictbor

adminforth/dataConnectors/sqlite.ts

@@ -155,17 +155,14 @@ class SQLiteConnector extends AdminForthBaseConnector implements IAdminForthData
       } else if (field.type == AdminForthDataTypes.BOOLEAN) {
         return value === null ? null : !!value;
       } else if (field.type == AdminForthDataTypes.JSON) {
-        if (field._underlineType == 'text' || field._underlineType == 'varchar') {
+        if (typeof value === 'string') {
           try {
             return JSON.parse(value);
           } catch (e) {
             return {'error': `Failed to parse JSON: ${e.message}`}
           }
-        } else {
-          afLogger.warn(`AdminForth: JSON field is not a string/text but ${field._underlineType}, this is not supported yet`);
         }
       }
-
       return value;
     }
 
@@ -192,12 +189,10 @@ class SQLiteConnector extends AdminForthBaseConnector implements IAdminForthData
       } else if (field.type == AdminForthDataTypes.BOOLEAN) {
         return value === null ? null : (value ? 1 : 0);
       } else if (field.type == AdminForthDataTypes.JSON) {
-        // check underline type is text or string
-        if (field._underlineType == 'text' || field._underlineType == 'varchar') {
-          return JSON.stringify(value);
-        } else {
-          afLogger.warn(`AdminForth: JSON field is not a string/text but ${field._underlineType}, this is not supported yet`);
+        if (value === null || value === undefined) {
+          return null;
         }
+        return typeof value === 'string' ? value : JSON.stringify(value);
       }
 
       return value;

adminforth/documentation/docs/tutorial/05-Adapters/02-oauth2-adapters.md

@@ -11,47 +11,47 @@ Used to authenticate users via OAuth 2.0 providers.
 ## Google OAuth Adapter
 
 ```bash
-pnpm i @adminforth/google-oauth-adapter
+pnpm i @adminforth/oauth-adapter-google
 ```
 
 Supports Google sign-in to allow users to authenticate using their Google or Google Workspaces accounts.
 
 ## GitHub OAuth Adapter
 
 ```bash
-pnpm i @adminforth/github-oauth-adapter
+pnpm i @adminforth/oauth-adapter-github
 ```
 
 Enables authentication via GitHub accounts, useful for developer tools and open-source apps.
 
 ## Facebook OAuth Adapter
 
 ```bash
-pnpm i @adminforth/facebook-oauth-adapter
+pnpm i @adminforth/oauth-adapter-facebook
 ```
 
 Allows users to log in with Facebook credentials. Facebook OAuth is commonly used for social media integrations.
 
 ## Keycloak OAuth Adapter
 
 ```bash
-pnpm i @adminforth/keycloak-oauth-adapter
+pnpm i @adminforth/oauth-adapter-keycloak
 ```
 
 Connects AdminForth to an open-source [Keycloak](https://www.keycloak.org/) identity provider for enterprise-grade SSO (Single Sign-On).
 
 ## Microsoft OAuth Adapter
 
 ```bash
-pnpm i @adminforth/microsoft-oauth-adapter
+pnpm i @adminforth/oauth-adapter-microsoft
 ```
 
 Supports login through Microsoft accounts including Azure AD, Office365, and Outlook.com.
 
 ## Twitch OAuth Adapter
 
 ```bash
-pnpm i @adminforth/twitch-oauth-adapter
+pnpm i @adminforth/oauth-adapter-twitch
 ```
 
 Adds support for Twitch authentication, useful for streaming or creator-oriented platforms.

adminforth/documentation/docs/tutorial/05-Adapters/09-chat-surface-adapters.md

@@ -7,13 +7,23 @@ sidebar_position: 8
 
 # Telegram Chat Surface Adapter
 
-Chat surface adapters connect external chat products to the [Agent plugin](/docs/tutorial/Plugins/agent/).
+Chat surface adapters connect external chat products to the [Agent plugin](/docs/tutorial/Plugins/agent/). They only receive and send chat messages. User linking is handled through OAuth connected accounts.
+
+For Telegram you need both adapters:
 
 ```bash
 pnpm i @adminforth/chat-surface-adapter-telegram
+pnpm i @adminforth/oauth-adapter-telegram
 ```
 
-Create a Telegram bot with BotFather and add the token to `.env`:
+Create a Telegram bot with BotFather and copy the token:
+
+1. Open [BotFather](https://t.me/BotFather).
+2. Click **Open** and open it in the Telegram app.
+3. Select or Create your bot.
+4. Copy the bot token shown at the top.
+
+Add the token to `.env`:
 
 ```env title=".env"
 TELEGRAM_BOT_TOKEN=your_bot_token
@@ -23,57 +33,62 @@ TELEGRAM_WEBHOOK_SECRET=your_random_secret
 
 The webhook secret confirms that the request came through Telegram.
 
-## Admin user field `externalUserId`
+## External identity `externalUserId`
 
-External chat accounts are linked by the Agent plugin, not by the Telegram adapter directly. The plugin stores linked external user ids in a JSON field on the AdminForth auth user resource.
+External chat accounts are resolved through OAuth connected accounts. The Telegram OAuth adapter writes the Telegram user id into `externalUserId` on the external identities resource. The Agent plugin then uses that field to map incoming Telegram messages to AdminForth users.
 
-By default this field is named `externalUserId`. Add it to your `adminuser` resource:
+Add the field to your external identities resource:
 
 ```ts
 {
   name: 'externalUserId',
-  type: AdminForthDataTypes.JSON,
+  type: AdminForthDataTypes.STRING,
 },
 ```
 
 Also add the matching column to your database schema and run a migration. For example, with Prisma and PostgreSQL:
 
 ```prisma title="schema.prisma"
-model adminuser {
-  // existing fields
-  externalUserId Json?
-}
-```
-
-For Prisma SQLite, store the same field as text:
-
-```prisma title="schema.prisma"
-model adminuser {
+model AdminUserExternalIdentity {
   // existing fields
   externalUserId String?
 }
 ```
 
-AdminForth should still define this resource column as `AdminForthDataTypes.JSON`; the SQLite connector serializes it into the text column and parses it back.
-
 Then create and apply the migration using your app's migration scripts:
 
 ```bash
-pnpm makemigration --name add-adminuser-external-user-id
+pnpm makemigration --name add-external-identity-external-user-id
 pnpm migrate:local
 ```
 
-When a Telegram account is linked, the field stores data like this:
+Configure the OAuth plugin with Telegram OAuth:
 
-```json
-{
-  "telegram": "123456789"
-}
-```
+```ts title="./resources/adminuser.ts"
+import OAuthPlugin from '@adminforth/oauth';
+import TelegramOauthAdapter from '@adminforth/oauth-adapter-telegram';
 
-If your field is named differently, configure `chatExternalIdsField` on the Agent plugin.
+new OAuthPlugin({
+  emailField: 'email',
+  externalIdentityResource: {
+    resourceId: 'admin_user_external_identities',
+    phoneField: 'phone',
+    fullNameField: 'fullName',
+    avatarUrlField: 'avatarUrl',
+    metaField: 'meta',
+  },
+  adapters: [
+    new TelegramOauthAdapter({
+      clientID: process.env.TELEGRAM_CLIENT_ID as string,
+      clientSecret: process.env.TELEGRAM_CLIENT_SECRET as string,
+      redirectUri: process.env.TELEGRAM_OAUTH_REDIRECT_URI as string,
+      scopes: ['openid', 'profile', 'phone'],
+    }),
+  ],
+});
+```
 
-Register the adapter in the Agent plugin:
+Then register the Telegram chat surface adapter in the Agent plugin:
 
 ```ts
 import AdminForthAgent from '@adminforth/agent';
@@ -103,28 +118,35 @@ new AdminForthAgent({
     }),
     //diff-add
   ],
-  // optional, defaults to 'externalUserId'
   //diff-add
-  chatExternalIdsField: 'externalUserId',
+  chatExternalIdentityResource: {
+    //diff-add
+    resourceId: 'admin_user_external_identities',
+    //diff-add
+    surfaces: {
+      //diff-add
+      telegram: {
+        //diff-add
+        provider: 'AdminForthAdapterTelegramOauth2',
+        //diff-add
+      },
+      //diff-add
+    },
+    //diff-add
+  },
 });
 ```
 
-When `botUsername` is configured, the Agent plugin adds **Chat Surfaces** to the user menu settings pages. A logged-in AdminForth user can open that page and click **Connect**. The Telegram adapter returns a URL like:
-
-```txt
-https://t.me/<botUsername>?start=<link-token>
-```
-
-After the user starts the bot with that token, AdminForth stores the Telegram user id in `externalUserId.telegram`. The same page also supports reconnecting and disconnecting the Telegram account.
+External chat users are resolved through OAuth connected accounts. Configure OAuth `externalIdentityResource` and Agent `chatExternalIdentityResource`, then let users connect Telegram from **Connected Accounts**.
 
-You can also prefill the JSON field manually if you do not want to use the connect page.
+The `provider` value must match the Telegram OAuth adapter class name. Users must connect Telegram in **Settings -> Connected Accounts** before the Telegram bot can identify them.
 
 ## Adapter options
 
 All options for `new TelegramChatSurfaceAdapter(options)`:
 
 - `botToken` (string, required) — Telegram bot token from BotFather.
-- `botUsername` (string, optional) — bot username used to build the account-link URL for the **Chat Surfaces** settings page.
+- `botUsername` (string, optional) — bot username. OAuth connected accounts are used for user linking.
 - `webhookSecret` (string, optional) — secret token configured in Telegram `setWebhook`.
 - `streamingMode` (`draft` | `typing` | `off`, optional) — streaming behavior for Telegram responses.
   - Default: `draft`.

adminforth/documentation/docs/tutorial/08-Plugins/01-agent.md

@@ -287,25 +287,41 @@ The plugin adds a chat surface to the admin UI, keeps session history per admin
 ## Chat surfaces (Telegram, etc.)
 
 By default, the Agent plugin exposes a chat surface inside the AdminForth admin UI.
-If you want to talk to the same agent from external chat products (Telegram, etc.), connect a **chat surface adapter**.
+If you want to talk to the same agent from external chat products (Telegram, Slack, Teams, etc.), configure both:
+
+- a **chat surface adapter** that receives messages from the external chat product
+- an **OAuth adapter** for the same provider so users can connect that external account in **Connected Accounts**
+
+For example, Telegram Agent access needs both `@adminforth/chat-surface-adapter-telegram` and `@adminforth/oauth-adapter-telegram`.
 
 Register adapters through `chatSurfaceAdapters`:
 
 ```ts
 import AdminForthAgent from '@adminforth/agent';
-import SomeChatSurfaceAdapter from '@adminforth/some-chat-surface-adapter';
+import TelegramChatSurfaceAdapter from '@adminforth/chat-surface-adapter-telegram';
 
 new AdminForthAgent({
   // ...modes, sessionResource, turnResource, etc.
   chatSurfaceAdapters: [
-    new SomeChatSurfaceAdapter({
-      // adapter-specific options
+    new TelegramChatSurfaceAdapter({
+      botToken: process.env.TELEGRAM_BOT_TOKEN as string,
+      webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET,
     }),
   ],
+  chatExternalIdentityResource: {
+    resourceId: 'admin_user_external_identities',
+    surfaces: {
+      telegram: {
+        provider: 'AdminForthAdapterTelegramOauth2',
+      },
+    },
+  },
 });
 ```
 
-When an adapter supports account linking, the Agent plugin adds a user menu settings page named **Chat Surfaces** where logged-in users can connect, reconnect, and disconnect external accounts.
+External chat users are resolved through the OAuth external identities resource. The `provider` value in `chatExternalIdentityResource.surfaces` must match the OAuth adapter class that writes connected accounts, for example `AdminForthAdapterTelegramOauth2`.
+
+Users connect their Telegram account from **Settings -> Connected Accounts**. After that, messages from the Telegram bot can be matched to the AdminForth user through the external identity `externalUserId`.
 
 For Telegram setup, including required user fields, webhook URL, environment variables, and adapter options, see: