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

package/dist/index.cjs.js

@@ -812,6 +812,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;
 /**
@@ -1961,6 +1983,22 @@ function computeUrl(type, region) {
 
 const uuid = () => uuid__default["default"].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)
  *
@@ -1980,6 +2018,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
@@ -2174,20 +2221,28 @@ const createHttpTransport = (endpoint) => {
         });
         return response;
     }, error => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const { response } = error;
         // handle unauthorized request
         if ((response === null || response === void 0 ? void 0 : response.data.code) === 400100 /* Amity.ServerError.UNAUTHORIZED */) {
             fireEvent('tokenTerminated', "terminated" /* Amity.SessionStates.TERMINATED */);
         }
+        // handle globally banned user. The realtime `user.didGlobalBan` event can be missed
+        // (e.g. MQTT dropped before delivery), so mirror the 400100 handling above and fire
+        // the same virtual event the login subscriptions already listen to. That terminates
+        // the session with `TokenTerminationReason.GLOBAL_BAN` and notifies `onClientBanned`
+        // consumers, instead of leaving the session `established` with a revoked token.
+        if (((_a = response === null || response === void 0 ? void 0 : response.data) === null || _a === void 0 ? void 0 : _a.code) === 400312 /* Amity.ServerError.GLOBAL_BAN */) {
+            fireEvent('user.didGlobalBan', { users: [], files: [] });
+        }
         // handle visitor daily usage limit exceeded
-        if (((_a = response === null || response === void 0 ? void 0 : response.data) === null || _a === void 0 ? void 0 : _a.code) === 400323 /* Amity.ServerError.VISITOR_USAGE_LIMIT_EXCEEDED */) {
+        if (((_b = response === null || response === void 0 ? void 0 : response.data) === null || _b === void 0 ? void 0 : _b.code) === 400323 /* Amity.ServerError.VISITOR_USAGE_LIMIT_EXCEEDED */) {
             throttledFireVisitorUsageLimit();
             throw new ASCError('Visitor usage limit exceeded', 400323 /* Amity.ServerError.VISITOR_USAGE_LIMIT_EXCEEDED */, "error" /* Amity.ErrorLevel.ERROR */);
         }
         // if it's an error with status in the response payload,
         // then it's an expected error.
-        if ((_b = response === null || response === void 0 ? void 0 : response.data) === null || _b === void 0 ? void 0 : _b.status) {
+        if ((_c = response === null || response === void 0 ? void 0 : response.data) === null || _c === void 0 ? void 0 : _c.status) {
             unwrapPayload(response === null || response === void 0 ? void 0 : response.data);
         }
         // as on request cancellation error is returned
@@ -2195,7 +2250,7 @@ const createHttpTransport = (endpoint) => {
             throw error;
         }
         // unexpected error.
-        throw new Error((_c = response === null || response === void 0 ? void 0 : response.data) !== null && _c !== void 0 ? _c : error);
+        throw new Error((_d = response === null || response === void 0 ? void 0 : response.data) !== null && _d !== void 0 ? _d : error);
     });
     instance.defaults.paramsSerializer = {
         encode: params => encodeURIComponent(params),
@@ -5465,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;
@@ -9189,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.
@@ -10234,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,
@@ -10257,6 +10488,7 @@ var index$t = /*#__PURE__*/Object.freeze({
     getShareableLinkConfiguration: getShareableLinkConfiguration,
     getProductCatalogueSetting: getProductCatalogueSetting,
     getForYouFeedSetting: getForYouFeedSetting,
+    getModuleSettings: getModuleSettings,
     loginAsVisitor: loginAsVisitor,
     loginAsBot: loginAsBot,
     getCurrentUser: getCurrentUser,
@@ -10284,7 +10516,8 @@ var index$t = /*#__PURE__*/Object.freeze({
     startMarkerSync: startMarkerSync,
     startUnreadSync: startUnreadSync,
     stopUnreadSync: stopUnreadSync,
-    getMarkerSyncConsistentMode: getMarkerSyncConsistentMode
+    getMarkerSyncConsistentMode: getMarkerSyncConsistentMode,
+    resolveModuleAvailability: resolveModuleAvailability
 });
 
 /* begin_public_function
@@ -21277,6 +21510,8 @@ const getChannel = (channelId, callback) => {
         onChannelMemberRemoved,
         onChannelMemberBanned,
         onChannelMemberUnbanned,
+        onChannelMemberRoleAdded,
+        onChannelMemberRoleRemoved,
         onChannelSetMuted,
         onChannelMessagePinned,
         onChannelMessageUnpinned,
@@ -36900,6 +37135,7 @@ class AmityAttachmentProductTags {
 exports.API_REGIONS = API_REGIONS;
 exports.AdRepository = index$6;
 exports.AmityAttachmentProductTags = AmityAttachmentProductTags;
+exports.AmityModuleNotEntitledError = AmityModuleNotEntitledError;
 exports.CategoryRepository = index$g;
 exports.ChannelRepository = index$k;
 exports.Client = index$t;
@@ -37008,6 +37244,7 @@ exports.pushToCache = pushToCache;
 exports.queryCache = queryCache;
 exports.queryOptions = queryOptions;
 exports.queryRoles = queryRoles;
+exports.resolveModuleAvailability = resolveModuleAvailability;
 exports.restoreCache = restoreCache;
 exports.runQuery = runQuery;
 exports.sortByChannelSegment = sortByChannelSegment;

package/dist/index.d.ts

@@ -35,4 +35,6 @@ export * as EventRepository from './eventRepository';
 export * as ProductRepository from './productRepository';
 export * as CuratedContentRepository from './curatedContentRepository';
 export { AmityAttachmentProductTags } from './productRepository/helpers';
+export { AmityModuleNotEntitledError } from './core/errors';
+export { resolveModuleAvailability } from './client/utils/resolveModuleAvailability';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAC;AAEzB,cAAc,WAAW,CAAC;AAG1B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AAEnD,cAAc,YAAY,CAAC;AAG3B,OAAO,KAAK,kBAAkB,MAAM,sBAAsB,CAAC;AAE3D,cAAc,cAAc,CAAC;AAG7B,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,oBAAoB,MAAM,wBAAwB,CAAC;AAE/D,cAAc,iBAAiB,CAAC;AAGhC,OAAO,KAAK,mBAAmB,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,kBAAkB,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,sBAAsB,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AAGrD,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAG/C,cAAc,gBAAgB,CAAC;AAE/B,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,oBAAoB,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,sBAAsB,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAE3E,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,wBAAwB,MAAM,4BAA4B,CAAC;AAEvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAC;AAEzB,cAAc,WAAW,CAAC;AAG1B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAE5B,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AAEnD,cAAc,YAAY,CAAC;AAG3B,OAAO,KAAK,kBAAkB,MAAM,sBAAsB,CAAC;AAE3D,cAAc,cAAc,CAAC;AAG7B,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,oBAAoB,MAAM,wBAAwB,CAAC;AAE/D,cAAc,iBAAiB,CAAC;AAGhC,OAAO,KAAK,mBAAmB,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,kBAAkB,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,sBAAsB,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AAGrD,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAG/C,cAAc,gBAAgB,CAAC;AAE/B,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,oBAAoB,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,sBAAsB,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAE3E,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,wBAAwB,MAAM,4BAA4B,CAAC;AAEvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAEzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC"}