@amityco/ts-sdk-react-native 7.5.3 → 7.6.0

package/src/client/api/resumeSession.ts

@@ -0,0 +1,282 @@
+import jwtDecode from 'jwt-decode';
+/* eslint-disable no-param-reassign */
+import { modifyMqttConnection } from '~/client/utils/modifyMqttConnection';
+/* eslint-disable require-atomic-updates */
+import { proxyWebsocketEvents } from '~/core/events';
+import { onChannelDeleted } from '~/channelRepository/events/onChannelDeleted';
+import { onChannelMemberBanned } from '~/channelRepository/events/onChannelMemberBanned';
+
+import { markReadEngineOnLoginHandler } from '~/subChannelRepository/utils/markReadEngine';
+import { onUserDeleted } from '~/userRepository/events/onUserDeleted';
+
+import analyticsEngineOnLoginHandler from '~/analytic/utils/analyticsEngineOnLoginHandler';
+import readReceiptSyncEngineOnLoginHandler from '~/client/utils/ReadReceiptSync/readReceiptSyncEngineOnLoginHandler';
+import legacyReadReceiptSyncEngineOnLoginHandler from '~/client/utils/ReadReceiptSync/legacyReadReceiptSyncEngineOnLoginHandler';
+import objectResolverEngineOnLoginHandler from '~/client/utils/ObjectResolver/objectResolverEngineOnLoginHandler';
+import { logout } from './logout';
+
+import { getActiveClient } from './activeClient';
+import { terminateClient } from './terminateClient';
+import { setActiveUser } from './activeUser';
+import { setSessionState } from './setSessionState';
+
+import { onClientBanned } from '../events';
+import { onTokenExpired } from '../events/onTokenExpired';
+import { onTokenTerminated } from '../events/onTokenTerminated';
+
+import { removeChannelMarkerCache } from '../utils/removeChannelMarkerCache';
+import { initializeMessagePreviewSetting } from '../utils/messagePreviewEngine';
+import { ASCError } from '~/core/errors';
+import SessionWatcher from '../utils/SessionWatcher';
+
+/*
+ * declared earlier to accomodate case when logging in with a different user
+ * than the one already connected, in which case the existing subscriptions need
+ * to be cleared
+ */
+let subscriptions: Amity.Unsubscriber[] = [];
+
+async function runMqtt() {
+  await modifyMqttConnection();
+}
+
+interface Params {
+  userId: string;
+  token: {
+    issuedAt: string;
+    expiresAt: string;
+    accessToken: string;
+  };
+}
+
+const isSameUserId = (token: Params['token']['accessToken']) => {
+  const client = getActiveClient();
+
+  const decoded = jwtDecode<{
+    user: {
+      userId: string;
+      publicUserId: string;
+      deviceInfo: Amity.Device['deviceInfo'];
+      networkId: string;
+      displayName: string;
+      refreshToken: string;
+    };
+  }>(token);
+
+  return decoded?.user?.publicUserId === client.userId;
+};
+
+const validateAccessToken = async ({ token, userId }: Params) => {
+  const client = getActiveClient();
+  // begin establishing session
+  setSessionState(Amity.SessionStates.ESTABLISHING);
+
+  const {
+    data: { users },
+  } = await client.http.get(`/api/v3/users/${userId}`, {
+    headers: {
+      Authorization: `Bearer ${token.accessToken}`,
+    },
+  });
+
+  const user = users.find((u: Amity.User) => u.userId === userId);
+
+  client.http.defaults.headers.common.Authorization = `Bearer ${token.accessToken}`;
+
+  client.http.defaults.metadata = {
+    tokenExpiry: token.expiresAt,
+    isGlobalBanned: false,
+    isUserDeleted: false,
+  };
+
+  client.upload.defaults.headers.common.Authorization = `Bearer ${token.accessToken}`;
+
+  client.upload.defaults.metadata = {
+    tokenExpiry: token.expiresAt,
+    isGlobalBanned: false,
+    isUserDeleted: false,
+  };
+
+  // manually setup the token for ws transport
+  if (client.ws) client.ws.io.opts.query = { token: token.accessToken };
+
+  client.token = token;
+
+  setSessionState(Amity.SessionStates.ESTABLISHED);
+
+  return user;
+};
+
+/* begin_public_function
+  id: client.resumeSession
+*/
+/**
+ * ```js
+ * import { resumeSession } from '@amityco/ts-sdk/client/api'
+ * const success = await resumeSession({
+ *   userId: 'XYZ123456789',
+ *   token: { accessToken: 'abc123', issuedAt: '2023-01-01T00:00:00Z', expiresAt: '2023-01-02T00:00:00Z' }
+ * })
+ * ```
+ *
+ * Connects an {@link Amity.Client} instance to ASC servers using an existing access token
+ *
+ * @param params the connect parameters
+ * @param params.userId the user ID for the current session
+ * @param params.token the existing access token with its metadata
+ * @param sessionHandler the session handler for token renewal
+ * @param config optional configuration
+ * @returns a success boolean if connected
+ *
+ * @category Client API
+ * @async
+ */
+export const resumeSession = async (
+  params: Params,
+  sessionHandler: Amity.SessionHandler,
+  config?: Amity.ConnectClientConfig,
+): Promise<boolean> => {
+  const client = getActiveClient();
+  let unsubWatcher: Amity.Unsubscriber;
+
+  client.log('client/api/resumeSession', {
+    apiKey: client.apiKey,
+    sessionState: client.sessionState,
+    ...params,
+  });
+
+  // Handle existing connected user
+  if (client.userId) {
+    if (client.userId === params.userId && isSameUserId(params.token.accessToken)) {
+      // Clear connections and listeners but preserve cache
+      if (client.mqtt && client.mqtt.connected) {
+        client.mqtt.disconnect();
+      }
+      if (client.ws && client.ws.connected) {
+        client.ws.disconnect();
+      }
+
+      // Clear existing subscriptions
+      subscriptions.forEach(fn => fn());
+      subscriptions = [];
+    } else {
+      // Different user - do full logout
+      await logout();
+
+      // Remove subscription to ban and delete
+      subscriptions.forEach(fn => fn());
+      subscriptions = [];
+    }
+  }
+
+  try {
+    const user = await validateAccessToken(params);
+
+    if (user == null) {
+      throw new ASCError(
+        `${params.userId} has not been found`,
+        Amity.ClientError.UNKNOWN_ERROR,
+        Amity.ErrorLevel.ERROR,
+      );
+    }
+
+    if (user.isDeleted) {
+      terminateClient(Amity.TokenTerminationReason.USER_DELETED);
+      return false;
+    }
+
+    if (user.isGlobalBanned) {
+      terminateClient(Amity.TokenTerminationReason.GLOBAL_BAN);
+      return false;
+    }
+
+    // FIXME: events are duplicated if connectClient is called few times without disconnectClient
+    // wire websocket events to our event emitter
+    proxyWebsocketEvents(client.ws, client.emitter);
+
+    client.ws?.open();
+
+    client.userId = user.userId;
+
+    client.sessionHandler = sessionHandler;
+
+    /*
+     * Cannot push to subscriptions as watcher needs to continue working even if
+     * token expires
+     */
+    unsubWatcher = client.accessTokenExpiryWatcher(sessionHandler);
+
+    setActiveUser(user);
+  } catch (error) {
+    /*
+     * if getting token failed session state reverts to initial state when app
+     * is first launched
+     */
+    SessionWatcher.getInstance().setSessionState(Amity.SessionStates.NOT_LOGGED_IN);
+
+    // pass error down tree so the calling function handle it
+    throw error;
+  }
+
+  if (config?.disableRTE !== true) {
+    runMqtt();
+  }
+
+  await initializeMessagePreviewSetting();
+
+  if (subscriptions.length === 0) {
+    subscriptions.push(
+      // GLOBAL_BAN
+      onClientBanned((_: Amity.UserPayload) => {
+        terminateClient(Amity.TokenTerminationReason.GLOBAL_BAN);
+
+        subscriptions.forEach(fn => fn());
+
+        unsubWatcher();
+      }),
+
+      onTokenTerminated(_ => {
+        terminateClient();
+
+        subscriptions.forEach(fn => fn());
+
+        unsubWatcher();
+      }),
+
+      onUserDeleted((user: Amity.InternalUser) => {
+        if (user.userId === client.userId) {
+          terminateClient(Amity.TokenTerminationReason.USER_DELETED);
+
+          subscriptions.forEach(fn => fn());
+
+          unsubWatcher();
+        }
+      }),
+
+      onTokenExpired(state => {
+        SessionWatcher.getInstance().setSessionState(state);
+
+        logout();
+
+        subscriptions.forEach(fn => fn());
+      }),
+
+      // NOTE: This is a temporary solution to handle the channel marker when the user is forced to leave
+      // the channel because currently backend can't handle this, so every time a user is banned from
+      // a channel or the channel is deleted the channel's unread count will not be reset to zero
+      onChannelDeleted(removeChannelMarkerCache),
+      onChannelMemberBanned(removeChannelMarkerCache),
+
+      markReadEngineOnLoginHandler(),
+      analyticsEngineOnLoginHandler(),
+      objectResolverEngineOnLoginHandler(),
+    );
+
+    if (client.useLegacyUnreadCount) {
+      subscriptions.push(readReceiptSyncEngineOnLoginHandler());
+    } else subscriptions.push(legacyReadReceiptSyncEngineOnLoginHandler());
+  }
+
+  return true;
+};
+/* end_public_function */

package/src/client/api/tests/resumeSession.test.ts

@@ -0,0 +1,173 @@
+import { ASCApiError } from '~/core/errors';
+import { user11, disconnectClient } from '~/utils/tests';
+import { resumeSession, createClient } from '..';
+import { setActiveClient } from '../activeClient';
+
+let client: Amity.Client;
+
+const sessionHandler: Amity.SessionHandler = {
+  sessionWillRenewAccessToken(_) {
+    // do nothing
+  },
+};
+
+const mockToken = {
+  accessToken: 'mock-access-token',
+  issuedAt: '2023-01-01T00:00:00Z',
+  expiresAt: '2025-01-01T00:00:00Z',
+};
+
+const mockUserResponse = {
+  data: {
+    users: [user11],
+  },
+};
+
+const onConnect = () =>
+  setTimeout(() => {
+    const CONNECT_PACKET = { type: 0, nsp: client.ws?.nsp };
+
+    client.ws?.emit('connect');
+
+    // simulate a connection ack packet from server
+    client.ws?.io.emit('packet', CONNECT_PACKET);
+  }, 50);
+
+describe('resumeSession', () => {
+  beforeEach(() => {
+    client = createClient('key', 'sg');
+    client.mqtt?.connect && (client.mqtt.connect = jest.fn());
+    client.mqtt?.subscribe && (client.mqtt.subscribe = jest.fn());
+    client.http.get = jest.fn().mockResolvedValueOnce(mockUserResponse);
+
+    setActiveClient(client);
+  });
+
+  afterEach(async () => {
+    if (client.sessionState === Amity.SessionStates.ESTABLISHED) await disconnectClient();
+  });
+
+  test('it should connect client with access token', async () => {
+    onConnect().unref();
+
+    const received = await resumeSession(
+      { userId: user11.userId, token: mockToken },
+      sessionHandler,
+    );
+
+    expect(received).toBe(true);
+  });
+
+  test('it should establish connection', async () => {
+    onConnect().unref();
+
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+    const { sessionState } = client;
+
+    expect(sessionState).toBe(Amity.SessionStates.ESTABLISHED);
+  });
+
+  test('it should have session state establishing while connecting client', () => {
+    resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    expect(client.sessionState).toBe(Amity.SessionStates.ESTABLISHING);
+  });
+
+  test('it should have session state notLoggedIn on failure', async () => {
+    client.http.get = jest
+      .fn()
+      .mockRejectedValue(
+        new ASCApiError('unauthorized', Amity.ServerError.UNAUTHORIZED, Amity.ErrorLevel.FATAL),
+      );
+
+    await expect(
+      resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler),
+    ).rejects.toThrow('unauthorized');
+    expect(client.sessionState).toBe(Amity.SessionStates.NOT_LOGGED_IN);
+  });
+
+  test('it should set authorization header with token', async () => {
+    onConnect().unref();
+
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    expect(client.http.defaults.headers.common.Authorization).toBe(
+      `Bearer ${mockToken.accessToken}`,
+    );
+    expect(client.upload.defaults.headers.common.Authorization).toBe(
+      `Bearer ${mockToken.accessToken}`,
+    );
+  });
+
+  test('it should set token metadata', async () => {
+    onConnect().unref();
+
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    expect(client.token).toEqual(mockToken);
+    expect(client.http.defaults.metadata).toEqual({
+      tokenExpiry: mockToken.expiresAt,
+      isGlobalBanned: false,
+      isUserDeleted: false,
+    });
+  });
+
+  test('it should call user endpoint to validate token', async () => {
+    onConnect().unref();
+
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    expect(client.http.get).toHaveBeenCalledWith(`/api/v3/users/${user11.userId}`);
+  });
+
+  test('it should terminate session on ban', async () => {
+    onConnect().unref();
+
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    // ban user
+    client.emitter.emit('user.didGlobalBan', {} as Amity.UserPayload);
+
+    expect(client.sessionState).toBe(Amity.SessionStates.TERMINATED);
+  });
+
+  test('it should reset client state when user is already connected with same userId', async () => {
+    onConnect().unref();
+
+    // First connection
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+    expect(client.sessionState).toBe(Amity.SessionStates.ESTABLISHED);
+    expect(client.userId).toBe(user11.userId);
+
+    // Mock the HTTP call for second connection
+    client.http.get = jest.fn().mockResolvedValueOnce(mockUserResponse);
+
+    // Second connection with same userId should treat as token expiry (preserve cache)
+    onConnect().unref();
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    // Verify that the client is properly reset and reconnected
+    expect(client.sessionState).toBe(Amity.SessionStates.ESTABLISHED);
+    expect(client.userId).toBe(user11.userId);
+  });
+
+  test('it should preserve cache when resuming session with same userId', async () => {
+    onConnect().unref();
+
+    // First connection - set some cache data
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+    if (client.cache) {
+      client.cache.data = { test: 'data' };
+    }
+
+    // Mock the HTTP call for second connection
+    client.http.get = jest.fn().mockResolvedValueOnce(mockUserResponse);
+
+    // Second connection with same userId
+    onConnect().unref();
+    await resumeSession({ userId: user11.userId, token: mockToken }, sessionHandler);
+
+    // Cache should be preserved when same userId is used
+    expect(client.cache?.data).toEqual({ test: 'data' });
+  });
+});

package/src/communityRepository/api/createCommunity.ts

@@ -1,3 +1,4 @@
+import { LinkedObject } from '~/utils/linkedObject';
 import { getActiveClient } from '~/client/api';
 
 import { ingestInCache } from '~/cache/api/ingestInCache';
@@ -10,8 +11,8 @@ import { prepareCommunityPayload, prepareCommunityRequest } from '../utils';
 */
 /**
  * ```js
- * import { createCommunity } from '@amityco/ts-sdk-react-native'
- * const created = await createCommunity({ communityId: 'foobar', displayName: 'foobar' })
+ * import { createCommunity } from '@amityco/ts-sdk'
+ * const created = await createCommunity({ communityId: 'foobar', displayName: 'foobar', isDiscoverable: true, requiresJoinApproval: false })
  * ```
  *
  * Creates an {@link Amity.Community}
@@ -33,6 +34,8 @@ export const createCommunity = async (
     | 'postSetting'
     | 'tags'
     | 'metadata'
+    | 'isDiscoverable'
+    | 'requiresJoinApproval'
   > &
     Amity.CommunityStorySettings & {
       userIds?: string[];
@@ -60,7 +63,7 @@ export const createCommunity = async (
 
   const { communities } = data;
   return {
-    data: communities[0],
+    data: LinkedObject.community(communities[0]),
     cachedAt,
   };
 };

package/src/communityRepository/api/deleteCommunity.ts

@@ -2,6 +2,7 @@ import { getActiveClient } from '~/client/api';
 
 import { fireEvent } from '~/core/events';
 import { getCommunity } from './getCommunity';
+import { LinkedObject } from '~/utils/linkedObject';
 
 /* begin_public_function
   id: community.delete
@@ -40,6 +41,6 @@ export const deleteCommunity = async (
     users: [],
   });
 
-  return deleted.data;
+  return LinkedObject.community(deleted.data);
 };
 /* end_public_function */

package/src/communityRepository/api/getCommunities.ts

@@ -5,6 +5,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 
 import { saveCommunityUsers } from '~/communityRepository/utils/saveCommunityUsers';
 import { prepareCommunityPayload } from '../utils';
+import { LinkedObject } from '~/utils/linkedObject';
 
 /**
  * ```js
@@ -22,15 +23,21 @@ import { prepareCommunityPayload } from '../utils';
  */
 export const getCommunities = async (
   communityIds: Amity.Community['communityId'][],
+  includeDiscoverablePrivateCommunity?: boolean,
 ): Promise<Amity.Cached<Amity.Community[]>> => {
   const client = getActiveClient();
   client.log('community/getCommunities', communityIds);
 
+  const encodedCommunityIds = communityIds.map(communityId => encodeURIComponent(communityId));
+
   // API-FIX: endpoint should not be /list, parameters should be querystring.
   const { data: payload } = await client.http.get<Amity.CommunityPayload>(
     `/api/v3/communities/list`,
     {
-      params: { communityIds },
+      params: {
+        communityIds: encodedCommunityIds,
+        includeDiscoverablePrivateCommunity: includeDiscoverablePrivateCommunity ?? true,
+      },
     },
   );
 
@@ -43,7 +50,7 @@ export const getCommunities = async (
   }
 
   return {
-    data: data.communities,
+    data: data.communities.map(community => LinkedObject.community(community)),
     cachedAt,
   };
 };

package/src/communityRepository/api/getCommunity.ts

@@ -5,6 +5,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 
 import { saveCommunityUsers } from '~/communityRepository/utils/saveCommunityUsers';
 import { prepareCommunityPayload } from '../utils';
+import { LinkedObject } from '~/utils/linkedObject';
 
 /**
  * ```js
@@ -22,13 +23,21 @@ import { prepareCommunityPayload } from '../utils';
  */
 export const getCommunity = async (
   communityId: Amity.Community['communityId'],
-): Promise<Amity.Cached<Amity.Community>> => {
+  type?: Amity.JoinRequestType,
+  includeDiscoverablePrivateCommunity?: boolean,
+): Promise<Amity.Cached<Amity.InternalCommunity>> => {
   const client = getActiveClient();
   client.log('community/getCommunity', communityId);
 
   // API-FIX: endpoint should not be /list, parameters should be querystring.
   const { data: payload } = await client.http.get<Amity.CommunityPayload>(
     `/api/v3/communities/${communityId}`,
+    {
+      params: {
+        type: 'communityJoinRequest',
+        includeDiscoverablePrivateCommunity: includeDiscoverablePrivateCommunity ?? true,
+      },
+    },
   );
 
   const data = prepareCommunityPayload(payload);
@@ -62,13 +71,13 @@ export const getCommunity = async (
  */
 getCommunity.locally = (
   communityId: Amity.Community['communityId'],
-): Amity.Cached<Amity.Community> | undefined => {
+): Amity.Cached<Amity.InternalCommunity> | undefined => {
   const client = getActiveClient();
   client.log('community/getCommunity.locally', communityId);
 
   if (!client.cache) return;
 
-  const cached = pullFromCache<Amity.Community>(['community', 'get', communityId]);
+  const cached = pullFromCache<Amity.InternalCommunity>(['community', 'get', communityId]);
 
   if (!cached) return;
 

package/src/communityRepository/api/getRecommendedCommunities.ts

@@ -4,6 +4,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 
 import { prepareCommunityPayload } from '../utils';
 import { COLLECTION_DEFAULT_PAGINATION_LIMIT } from '~/utils/constants';
+import { LinkedObject } from '~/utils/linkedObject';
 
 /* begin_public_function
   id: community.query.recommended_communities
@@ -24,18 +25,24 @@ import { COLLECTION_DEFAULT_PAGINATION_LIMIT } from '~/utils/constants';
  * @private
  */
 export const getRecommendedCommunities = async (
-  query?: Amity.PageLimit,
+  query?: Amity.PageLimit & { includeDiscoverablePrivateCommunity?: boolean },
 ): Promise<Amity.Cached<Amity.Community[]>> => {
   const client = getActiveClient();
   client.log('community/getRecommendedCommunities', query);
 
-  const { limit = COLLECTION_DEFAULT_PAGINATION_LIMIT } = query ?? {};
+  const { limit = COLLECTION_DEFAULT_PAGINATION_LIMIT, includeDiscoverablePrivateCommunity } =
+    query ?? {};
 
   // API-FIX: backend doesnt answer Amity.Response
   // const { data: payload } = await client.http.get<Amity.Response<CommunityPayload>>(
   const { data: payload } = await client.http.get<Amity.CommunityPayload>(
     `/api/v3/communities/recommended`,
-    { params: { options: { limit } } },
+    {
+      params: {
+        includeDiscoverablePrivateCommunity: includeDiscoverablePrivateCommunity ?? true,
+        options: { limit },
+      },
+    },
   );
 
   const data = prepareCommunityPayload(payload);
@@ -47,5 +54,5 @@ export const getRecommendedCommunities = async (
     ingestInCache(data, { cachedAt });
   }
 
-  return { data: communities, cachedAt };
+  return { data: communities.map(community => LinkedObject.community(community)), cachedAt };
 };

package/src/communityRepository/api/getTrendingCommunities.ts

@@ -4,6 +4,7 @@ import { ingestInCache } from '~/cache/api/ingestInCache';
 
 import { prepareCommunityPayload } from '../utils';
 import { COLLECTION_DEFAULT_PAGINATION_LIMIT } from '~/utils/constants';
+import { LinkedObject } from '~/utils/linkedObject';
 
 /**
  * ```js
@@ -21,18 +22,24 @@ import { COLLECTION_DEFAULT_PAGINATION_LIMIT } from '~/utils/constants';
  * @private
  */
 export const getTrendingCommunities = async (
-  query?: Amity.PageLimit,
+  query?: Amity.PageLimit & { includeDiscoverablePrivateCommunity?: boolean },
 ): Promise<Amity.Cached<Amity.Community[]>> => {
   const client = getActiveClient();
   client.log('community/getTrendingCommunities', query);
 
-  const { limit = COLLECTION_DEFAULT_PAGINATION_LIMIT } = query ?? {};
+  const { limit = COLLECTION_DEFAULT_PAGINATION_LIMIT, includeDiscoverablePrivateCommunity } =
+    query ?? {};
 
   // API-FIX: backend doesnt answer Amity.Response
   // const { data } = await client.http.get<Amity.Response<CommunityPayload>>(
   const { data: payload } = await client.http.get<Amity.CommunityPayload>(
     `/api/v3/communities/top-trending`,
-    { params: { options: { limit } } },
+    {
+      params: {
+        includeDiscoverablePrivateCommunity: includeDiscoverablePrivateCommunity ?? true,
+        options: { limit },
+      },
+    },
   );
 
   const data = prepareCommunityPayload(payload);
@@ -44,5 +51,5 @@ export const getTrendingCommunities = async (
     ingestInCache(data, { cachedAt });
   }
 
-  return { data: communities, cachedAt };
+  return { data: communities.map(community => LinkedObject.community(community)), cachedAt };
 };

package/src/communityRepository/api/joinCommunity.ts

@@ -1,9 +1,12 @@
-import { getActiveClient } from '~/client/api';
+import { getActiveClient } from '~/client/api/activeClient';
 
 import { ingestInCache } from '~/cache/api/ingestInCache';
 import { prepareCommunityPayload } from '~/communityRepository/utils';
 import { fireEvent } from '~/core/events';
 
+/**
+ * @deprecated This function will to be deprecated and use the new community.join().
+ */
 /* begin_public_function
   id: community.join
 */