@amityco/ts-sdk 7.27.1-7ad3a1bf.0 → 7.27.1-8317d53.0

package/dist/index.esm.js

@@ -796,6 +796,28 @@ class ASCConnectionError extends ASCError {
         this.event = event;
     }
 }
+/**
+ * Thrown when the network does not own a module the call needs. Raised from
+ * any module endpoint under `enforce` enforcement, mapped from app code
+ * `400325` — never from HTTP 403 alone, which already covers a role problem
+ * (`400300` / `400301`), a visitor (`403999`) and a bot (`403998`).
+ *
+ * `modules` carries **every** key the refusal named, as raw strings, so a
+ * caller can say which entitlement is absent without a second request.
+ *
+ * @category Errors
+ */
+class AmityModuleNotEntitledError extends ASCApiError {
+    /**
+     * @param message The server's message, e.g. `Module not entitled: chat, live`
+     * @param modules Every module key from the rejection's `data.modules`
+     */
+    constructor(message, modules = []) {
+        super(message, 400325 /* Amity.ServerError.MODULE_NOT_ENTITLED */, "error" /* Amity.ErrorLevel.ERROR */);
+        this.modules = modules;
+        this.type = 'AmityModuleNotEntitledError';
+    }
+}
 
 let activeClient = null;
 /**
@@ -1945,6 +1967,22 @@ function computeUrl(type, region) {
 
 const uuid = () => uuid$1.v4().toString();
 
+/**
+ * Reads the module keys a `MODULE_NOT_ENTITLED` rejection named.
+ *
+ * Every entry is kept, as a raw string: one call can need more than one
+ * module, and a key this build predates is still the only part of the
+ * payload a customer can act on.
+ *
+ * @category Transport
+ * @hidden
+ */
+const extractNotEntitledModules = (data) => {
+    const { modules } = data !== null && data !== void 0 ? data : {};
+    if (!Array.isArray(modules))
+        return [];
+    return modules.filter((module) => typeof module === 'string');
+};
 /**
  * Unwraps v3 server payload (for error handling and type extraction)
  *
@@ -1964,6 +2002,15 @@ const unwrapPayload = (response) => {
         throw new ASCUnknownError(response.code);
     }
     else if (response.status === 'error') {
+        /*
+         * An entitlement refusal must not arrive as a generic failure: a customer
+         * cannot then tell a module they have not bought from an outage. Keyed on
+         * the app code, never on the HTTP status, so a role or membership problem
+         * still maps to the generic error.
+         */
+        if (response.code === 400325 /* Amity.ServerError.MODULE_NOT_ENTITLED */) {
+            throw new AmityModuleNotEntitledError(response.message, extractNotEntitledModules(response.data));
+        }
         throw new ASCApiError(response.message, response.code, "error" /* Amity.ErrorLevel.ERROR */);
     }
     // unjust, but helps force uncast "T | undefined" to allow deconstruction without warnings
@@ -5473,6 +5520,95 @@ const getForYouFeedSetting = async () => {
 };
 /* end_public_function */
 
+const ENFORCEMENT_MODES = ['off', 'shadow', 'enforce'];
+/**
+ * An unrecognised mode decodes to `off`, and so does an absent one. A mode
+ * this build does not know must not withhold anything — defaulting to
+ * `enforce` would let a server-side rename black out a customer's app.
+ *
+ * @category private
+ */
+const parseEnforcement = (mode) => {
+    const match = ENFORCEMENT_MODES.find(value => value === mode);
+    return match !== null && match !== void 0 ? match : 'off';
+};
+const parseGrants = (modules) => {
+    const grants = {};
+    Object.entries(modules !== null && modules !== void 0 ? modules : {}).forEach(([key, granted]) => {
+        grants[key] = granted === true;
+    });
+    return grants;
+};
+/**
+ * Every catalog entry survives, including one whose key this build has never
+ * heard of, so a module added server-side is still listable.
+ *
+ * @category private
+ */
+const parseCatalog = (catalog) => {
+    const parsed = {};
+    Object.entries(catalog !== null && catalog !== void 0 ? catalog : {}).forEach(([key, definition]) => {
+        const rawRequires = definition === null || definition === void 0 ? void 0 : definition.requires;
+        const requires = Array.isArray(rawRequires)
+            ? rawRequires.filter((entry) => typeof entry === 'string')
+            : [];
+        parsed[key] = {
+            label: typeof (definition === null || definition === void 0 ? void 0 : definition.label) === 'string' ? definition.label : key,
+            kind: (definition === null || definition === void 0 ? void 0 : definition.kind) === 'setting' ? 'setting' : 'api',
+            requires,
+        };
+    });
+    return parsed;
+};
+/**
+ * Decodes `GET /api/v3/network-settings/modules`. Nothing is trimmed: the
+ * catalog is the dependency table callers resolve against, and a client that
+ * cannot see it has to hardcode one.
+ *
+ * @category private
+ */
+const parseModuleSettings = (raw) => {
+    var _a;
+    return ({
+        enforcement: parseEnforcement((_a = raw === null || raw === void 0 ? void 0 : raw.enforcement) !== null && _a !== void 0 ? _a : raw === null || raw === void 0 ? void 0 : raw.mode),
+        modules: parseGrants(raw === null || raw === void 0 ? void 0 : raw.modules),
+        catalog: parseCatalog(raw === null || raw === void 0 ? void 0 : raw.catalog),
+    });
+};
+
+/* begin_public_function
+  id: client.getModuleSettings
+*/
+/**
+ * ```js
+ * import { Client } from '@amityco/ts-sdk'
+ * const moduleSettings = await Client.getModuleSettings()
+ * ```
+ *
+ * Fetches the network's module entitlements: which modules the network was
+ * granted, whether core is enforcing those grants, and the catalog of all
+ * modules with their dependency chains.
+ *
+ * The payload is returned whole — `catalog` is the dependency table
+ * {@link resolveModuleAvailability} reads, and a client that cannot see it has
+ * to hardcode one.
+ *
+ * The read is **advisory**. It tells a host what to offer; under `enforce` the
+ * backend refuses a call to an unowned module regardless of what was resolved
+ * here, and that refusal arrives as `AmityModuleNotEntitledError`.
+ *
+ * @returns A Promise of {@link Amity.ModuleSettings} object
+ *
+ * @category Client API
+ * @async
+ */
+const getModuleSettings = async () => {
+    const client = getActiveClient();
+    const { data } = await client.http.get(`/api/v3/network-settings/modules`);
+    return parseModuleSettings(data);
+};
+/* end_public_function */
+
 const checkUserPermission = (userId, permission) => {
     var _a;
     const user = (_a = pullFromCache(['user', 'get', userId])) === null || _a === void 0 ? void 0 : _a.data;
@@ -9197,6 +9333,7 @@ const createClient = (apiKey, apiRegion = API_REGIONS.SG, { debugSession = DEFAU
         getMarkerSyncConsistentMode,
         getProductCatalogueSetting,
         getForYouFeedSetting,
+        getModuleSettings,
         /**
          * Prefix for the deviceId key in the local storage or async storage.
          * This is allow user to have multiple SDK client and Mqtt client within the same app.
@@ -10242,6 +10379,92 @@ const getUserUnread = (callback) => {
     };
 };
 
+/**
+ * ```js
+ * import { Client, resolveModuleAvailability } from '@amityco/ts-sdk'
+ *
+ * const moduleSettings = await Client.getModuleSettings()
+ *
+ * if (resolveModuleAvailability(moduleSettings, 'live').isAvailable) {
+ *   // offer the Live entry point
+ * }
+ * ```
+ *
+ * Resolves whether one module is usable on this network.
+ *
+ * Availability is a function of all three fields of
+ * {@link Amity.ModuleSettings} — the enforcement mode, the module's own grant,
+ * and its prerequisite chain — combined in that order. Reading `modules`
+ * directly contradicts the mode: staging answers `mode: 'off'` with
+ * `modules: {}`, and every module still works.
+ *
+ * The dependency table comes from the payload's `catalog`, never from a
+ * hardcoded copy, so a chain the backend changes takes effect without an SDK
+ * release.
+ *
+ * The SDK does not hold the settings — the caller keeps what it fetched and
+ * resolves against it. With no settings at all (a fetch that never succeeded)
+ * the caller reads that as every module available: under `enforce` the backend
+ * refuses the calls anyway, so the exposure is a screen that offers too much,
+ * not one that withholds what a customer paid for.
+ *
+ * @param moduleSettings The network's module settings
+ * @param moduleKey The module to resolve — an {@link Amity.ModuleKey}, so the
+ * 15 keys this build knows complete and type-check while a catalog entry it
+ * does not know still resolves.
+ * @returns An {@link Amity.ModuleAvailability} answer
+ *
+ * @category Client API
+ */
+const resolveModuleAvailability = (moduleSettings, moduleKey, seen = new Set()) => {
+    var _a, _b, _c, _d, _e;
+    const isGranted = (_a = moduleSettings.modules[moduleKey]) !== null && _a !== void 0 ? _a : false;
+    /*
+     * Not enforcing: nothing is withheld, and no graph walk is needed. This has
+     * to come first — `off` and `shadow` resolve available whatever the grant
+     * says, and a cycle would otherwise return unavailable under `off` too.
+     */
+    if (moduleSettings.enforcement !== 'enforce') {
+        return { moduleKey, isAvailable: true, isGranted };
+    }
+    // A cycle in `requires` resolves unavailable rather than recursing.
+    if (seen.has(moduleKey)) {
+        return {
+            moduleKey,
+            isAvailable: false,
+            isGranted,
+            reason: 'prerequisiteUnavailable',
+            unsatisfied: (_c = (_b = moduleSettings.catalog[moduleKey]) === null || _b === void 0 ? void 0 : _b.requires) !== null && _c !== void 0 ? _c : [],
+        };
+    }
+    // The module's own grant is evaluated before its prerequisites, so
+    // `notGranted` is reported in preference when both hold.
+    if (!isGranted) {
+        return { moduleKey, isAvailable: false, isGranted, reason: 'notGranted' };
+    }
+    const requires = (_e = (_d = moduleSettings.catalog[moduleKey]) === null || _d === void 0 ? void 0 : _d.requires) !== null && _e !== void 0 ? _e : [];
+    if (requires.length === 0)
+        return { moduleKey, isAvailable: true, isGranted };
+    // `requires` is satisfied by any one entry, transitively.
+    const isSatisfied = requires.some(dependency => resolveModuleAvailability(moduleSettings, dependency, new Set([...seen, moduleKey]))
+        .isAvailable);
+    if (isSatisfied)
+        return { moduleKey, isAvailable: true, isGranted };
+    /*
+     * `unsatisfied` carries the whole `requires` list rather than one entry. Any
+     * one of them would have satisfied the requirement, so naming a single
+     * module misdirects: telling a Community-only customer "Comment needs post"
+     * hides that Story would also have done.
+     */
+    return {
+        moduleKey,
+        isAvailable: false,
+        isGranted,
+        reason: 'prerequisiteUnavailable',
+        unsatisfied: requires,
+    };
+};
+
 var index$t = /*#__PURE__*/Object.freeze({
     __proto__: null,
     getActiveClient: getActiveClient,
@@ -10265,6 +10488,7 @@ var index$t = /*#__PURE__*/Object.freeze({
     getShareableLinkConfiguration: getShareableLinkConfiguration,
     getProductCatalogueSetting: getProductCatalogueSetting,
     getForYouFeedSetting: getForYouFeedSetting,
+    getModuleSettings: getModuleSettings,
     loginAsVisitor: loginAsVisitor,
     loginAsBot: loginAsBot,
     getCurrentUser: getCurrentUser,
@@ -10292,7 +10516,8 @@ var index$t = /*#__PURE__*/Object.freeze({
     startMarkerSync: startMarkerSync,
     startUnreadSync: startUnreadSync,
     stopUnreadSync: stopUnreadSync,
-    getMarkerSyncConsistentMode: getMarkerSyncConsistentMode
+    getMarkerSyncConsistentMode: getMarkerSyncConsistentMode,
+    resolveModuleAvailability: resolveModuleAvailability
 });
 
 /* begin_public_function
@@ -27110,73 +27335,31 @@ const declineComment = async (commentId, reason) => {
 };
 /* end_public_function */
 
-const FLAG_REASONS = Object.values(ContentFlagReasonEnum);
-/**
- * Legacy string / undefined input. Byte-for-byte the previous mapping:
- * predefined value → `{ reason, detail: '' }`; any other non-empty string (including
- * the literal `'Others'`) → `{ reason: 'Others', detail: string }`; `undefined` or `''`
- * → `{ reason: 'Others', detail: '' }`.
- */
-const toLegacyFlagCommentBody = (reason) => {
-    if (reason && reason !== ContentFlagReasonEnum.Others && FLAG_REASONS.includes(reason)) {
-        return { reason, detail: '' };
-    }
-    return { reason: ContentFlagReasonEnum.Others, detail: reason || '' };
-};
-const invalidFlagCommentOptions = (message) => new ASCError(`flagComment: ${message}`, 800110 /* Amity.ClientError.INVALID_PARAMETERS */, "error" /* Amity.ErrorLevel.ERROR */);
-/**
- * New options input. Validated before any request is made: the argument must be a
- * plain object, `reason` must be one of the nine `ContentFlagReasonEnum` values and
- * `detail`, when supplied, must be a string. `detail` is forwarded unchanged and is
- * omitted from the body when `undefined`.
- */
-const toFlagCommentBody = (options) => {
-    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
-        throw invalidFlagCommentOptions('expected an options object `{ reason, detail? }` or a legacy reason string');
-    }
-    const { reason, detail } = options;
-    if (typeof reason !== 'string' || !FLAG_REASONS.includes(reason)) {
-        throw invalidFlagCommentOptions('`reason` must be a `ContentFlagReasonEnum` value');
-    }
-    if (detail !== undefined && typeof detail !== 'string') {
-        throw invalidFlagCommentOptions('`detail` must be a string when supplied');
-    }
-    return detail === undefined ? { reason } : { reason, detail };
-};
 /* begin_public_function
   id: comment.flag
 */
 /**
  * ```js
- * import { CommentRepository, ContentFlagReasonEnum } from '@amityco/ts-sdk'
- *
- * // No reason: sent as Others with an empty detail.
- * await CommentRepository.flagComment(commentId)
- *
- * // Category plus optional reporter context (any category, including Others).
- * await CommentRepository.flagComment(commentId, {
- *   reason: ContentFlagReasonEnum.SpamOrScams,
- *   detail: 'Repeated promotional links',
- * })
+ * import { CommentRepository } from '@amityco/ts-sdk'
+ * const flagged = await CommentRepository.flagComment(commentId, reason)
  * ```
  *
- * Reports a comment to moderation. Three call shapes are accepted (see the overloads):
- * id-only, an options object, and the deprecated legacy reason string.
- *
  * @param commentId The ID of the comment to flag
- * @param input an options object `{ reason, detail? }`, a legacy reason string, or nothing
- * @returns `true` when the report was created
+ * @param reason the reason to flag the comment
+ * @returns the created report result
  *
  * @category Comment API
  * @async
  * */
-const flagComment = async (commentId, input) => {
+const flagComment = async (commentId, reason) => {
     const client = getActiveClient();
     client.log('comment/flagComment', commentId);
-    // Dispatch on the public input shape first, then apply the matching normalization.
-    const body = input === undefined || typeof input === 'string'
-        ? toLegacyFlagCommentBody(input)
-        : toFlagCommentBody(input);
+    const isPredefinedReason = reason &&
+        Object.entries(ContentFlagReasonEnum).some(([key, value]) => key !== ContentFlagReasonEnum.Others && value === reason);
+    const body = {
+        reason: reason && isPredefinedReason ? reason : ContentFlagReasonEnum.Others,
+        detail: reason && !isPredefinedReason ? reason : '',
+    };
     const { data: payload } = await client.http.post(`/api/v3/comments/${encodeURIComponent(commentId)}/flag`, body);
     if (client.cache) {
         ingestInCache(payload);
@@ -36949,4 +37132,4 @@ class AmityAttachmentProductTags {
     }
 }
 
-export { API_REGIONS, index$6 as AdRepository, AmityAttachmentProductTags, AmityAutoSubscription, AmityChannelNotificationModeEnum, AmityCommunityType, AmityEventOrderOption, AmityEventOriginType, AmityEventResponseStatus, AmityEventSortOption, AmityEventStatus, AmityEventType, AmityLiveViewerCountMode, AmitySharableContentType, AnalyticsSourceTypeEnum, index$g as CategoryRepository, index$k as ChannelRepository, index$t as Client, index$f as CommentRepository, CommunityNotificationEventNameEnum, CommunityPostSettingMaps, CommunityPostSettings, index$h as CommunityRepository, ContentFeedType, ContentFlagReasonEnum, index as CuratedContentRepository, DefaultCommunityPostSetting, index$2 as EventRepository, FeedDataTypeEnum, index$e as FeedRepository, FeedSortByEnum, FeedSourceEnum, FeedTypeEnum, FileAccessTypeEnum, index$q as FileRepository, FileType, GET_WATCHER_URLS, index$4 as InvitationRepository, InvitationSortByEnum, InvitationStatusEnum, InvitationTargetTypeEnum, InvitationTypeEnum, JoinRequestStatusEnum, JoinResultStatusEnum, index$3 as LiveReactionRepository, index$8 as LiveStreamPlayer, MembershipAcceptanceTypeEnum, MessageContentType, index$o as MessageRepository, NotificationRolesFilterTypeEnum, NotificationSettingsLevelEnum, index$9 as PollRepository, PostContentType, index$c as PostRepository, PostStructureType, index$1 as ProductRepository, index$p as ReactionRepository, index$a as RoomPresenceRepository, index$d as RoomRepository, SearchUsersByEnum, index$7 as StoryRepository, index$b as StreamRepository, index$n as SubChannelRepository, SubscriptionLevels, UserNotificationModuleNameEnum, UserReportTypeEnum, index$r as UserRepository, UserTypeEnum, VERSION, VideoResolution, VideoSize, VideoTranscodingStatus, backupCache, createQuery, createReport, createUserToken, deleteReport, disableCache, dropFromCache, enableCache, exceedsUntilAtBoundary, filterByChannelMembership, filterByCommunityMembership, filterByFeedType, filterByPostDataTypes, filterByPropEquality, filterByPropInclusion, filterByPropIntersection, filterBySearchTerm, filterByStringComparePartially, filterByUntilAt, filterCommentsByBlockUsers, filterPostsByBlockUsers, getBlockUsersId, getChannelTopic, getCommentTopic, getCommunityStoriesTopic, getCommunityTopic, getLiveReactionTopic, getLiveStreamTopic, getMarkedMessageTopic, getMarkerUserFeedTopic, getMessageTopic, getMyFollowersTopic, getMyFollowingsTopic, getNetworkId, getNetworkTopic, getPostTopic, getRole, getRoomStreamerTopic, getRoomWatcherTopic, getSmartFeedChannelTopic, getSmartFeedMessageTopic, getSmartFeedSubChannelTopic, getStoryTopic, getSubChannelTopic, getUserTopic, isAfterBefore, isAfterBeforeRaw, isCachable, isFetcher, isFresh, isLocal, isMutator, isOffline, isPaged, isReportedByMe, isSkip, mergeInCache, index$5 as notificationTray, onChannelMarkerFetched, onFeedMarkerFetched, onFeedMarkerUpdated, onMessageMarked, onMessageMarkerFetched, onSubChannelMarkerFetched, onSubChannelMarkerUpdated, onUserMarkerFetched, onUserMarkerFetchedLegacy, pullFromCache, pushToCache, queryCache, queryOptions, queryRoles, restoreCache, runQuery, sortByChannelSegment, sortByDisplayName, sortByFirstCreated, sortByFirstUpdated, sortByLastActivity, sortByLastCreated, sortByLastUpdated, sortByLocalSortingDate, sortByName, sortBySegmentNumber, subscribeTopic, toPage, toPageRaw, toToken, upsertInCache, validateUntilAt, wipeCache };
+export { API_REGIONS, index$6 as AdRepository, AmityAttachmentProductTags, AmityAutoSubscription, AmityChannelNotificationModeEnum, AmityCommunityType, AmityEventOrderOption, AmityEventOriginType, AmityEventResponseStatus, AmityEventSortOption, AmityEventStatus, AmityEventType, AmityLiveViewerCountMode, AmityModuleNotEntitledError, AmitySharableContentType, AnalyticsSourceTypeEnum, index$g as CategoryRepository, index$k as ChannelRepository, index$t as Client, index$f as CommentRepository, CommunityNotificationEventNameEnum, CommunityPostSettingMaps, CommunityPostSettings, index$h as CommunityRepository, ContentFeedType, ContentFlagReasonEnum, index as CuratedContentRepository, DefaultCommunityPostSetting, index$2 as EventRepository, FeedDataTypeEnum, index$e as FeedRepository, FeedSortByEnum, FeedSourceEnum, FeedTypeEnum, FileAccessTypeEnum, index$q as FileRepository, FileType, GET_WATCHER_URLS, index$4 as InvitationRepository, InvitationSortByEnum, InvitationStatusEnum, InvitationTargetTypeEnum, InvitationTypeEnum, JoinRequestStatusEnum, JoinResultStatusEnum, index$3 as LiveReactionRepository, index$8 as LiveStreamPlayer, MembershipAcceptanceTypeEnum, MessageContentType, index$o as MessageRepository, NotificationRolesFilterTypeEnum, NotificationSettingsLevelEnum, index$9 as PollRepository, PostContentType, index$c as PostRepository, PostStructureType, index$1 as ProductRepository, index$p as ReactionRepository, index$a as RoomPresenceRepository, index$d as RoomRepository, SearchUsersByEnum, index$7 as StoryRepository, index$b as StreamRepository, index$n as SubChannelRepository, SubscriptionLevels, UserNotificationModuleNameEnum, UserReportTypeEnum, index$r as UserRepository, UserTypeEnum, VERSION, VideoResolution, VideoSize, VideoTranscodingStatus, backupCache, createQuery, createReport, createUserToken, deleteReport, disableCache, dropFromCache, enableCache, exceedsUntilAtBoundary, filterByChannelMembership, filterByCommunityMembership, filterByFeedType, filterByPostDataTypes, filterByPropEquality, filterByPropInclusion, filterByPropIntersection, filterBySearchTerm, filterByStringComparePartially, filterByUntilAt, filterCommentsByBlockUsers, filterPostsByBlockUsers, getBlockUsersId, getChannelTopic, getCommentTopic, getCommunityStoriesTopic, getCommunityTopic, getLiveReactionTopic, getLiveStreamTopic, getMarkedMessageTopic, getMarkerUserFeedTopic, getMessageTopic, getMyFollowersTopic, getMyFollowingsTopic, getNetworkId, getNetworkTopic, getPostTopic, getRole, getRoomStreamerTopic, getRoomWatcherTopic, getSmartFeedChannelTopic, getSmartFeedMessageTopic, getSmartFeedSubChannelTopic, getStoryTopic, getSubChannelTopic, getUserTopic, isAfterBefore, isAfterBeforeRaw, isCachable, isFetcher, isFresh, isLocal, isMutator, isOffline, isPaged, isReportedByMe, isSkip, mergeInCache, index$5 as notificationTray, onChannelMarkerFetched, onFeedMarkerFetched, onFeedMarkerUpdated, onMessageMarked, onMessageMarkerFetched, onSubChannelMarkerFetched, onSubChannelMarkerUpdated, onUserMarkerFetched, onUserMarkerFetchedLegacy, pullFromCache, pushToCache, queryCache, queryOptions, queryRoles, resolveModuleAvailability, restoreCache, runQuery, sortByChannelSegment, sortByDisplayName, sortByFirstCreated, sortByFirstUpdated, sortByLastActivity, sortByLastCreated, sortByLastUpdated, sortByLocalSortingDate, sortByName, sortBySegmentNumber, subscribeTopic, toPage, toPageRaw, toToken, upsertInCache, validateUntilAt, wipeCache };