@amityco/ts-sdk 7.29.0 → 7.29.1-c2a29dc.0

package/dist/index.esm.js

@@ -42,6 +42,33 @@ var UserReportTypeEnum;
     UserReportTypeEnum["AVATAR"] = "avatarFileId";
     UserReportTypeEnum["BEHAVIOR"] = "behavior";
 })(UserReportTypeEnum || (UserReportTypeEnum = {}));
+/**
+ * The profile field a user is reported for in `UserRepository.flagUserProfile`.
+ * Each member is the backend `reportType` wire value. There is deliberately no
+ * behavior member: behavior reports need a reason and go through
+ * `UserRepository.flagUserBehavior`.
+ */
+var UserProfileFieldEnum;
+(function (UserProfileFieldEnum) {
+    UserProfileFieldEnum["DISPLAY_NAME"] = "displayName";
+    UserProfileFieldEnum["DESCRIPTION"] = "description";
+    UserProfileFieldEnum["AVATAR"] = "avatarFileId";
+})(UserProfileFieldEnum || (UserProfileFieldEnum = {}));
+/**
+ * Selects which of the caller's reports `UserRepository.unflagUser` withdraws, sent as the
+ * `reportType` query parameter. The four typed members are the backend `reportType` wire
+ * values and match `UserReportTypeEnum`. `UNTYPED` selects the typeless (legacy) report,
+ * which `isUserFlaggedByMe` returns as `reportType: null`; it is a selector only, never
+ * stored, and the flag endpoint refuses it.
+ */
+var UserReportTypeFilterEnum;
+(function (UserReportTypeFilterEnum) {
+    UserReportTypeFilterEnum["DISPLAY_NAME"] = "displayName";
+    UserReportTypeFilterEnum["DESCRIPTION"] = "description";
+    UserReportTypeFilterEnum["AVATAR"] = "avatarFileId";
+    UserReportTypeFilterEnum["BEHAVIOR"] = "behavior";
+    UserReportTypeFilterEnum["UNTYPED"] = "untyped";
+})(UserReportTypeFilterEnum || (UserReportTypeFilterEnum = {}));
 
 const FileType = Object.freeze({
     FILE: 'file',
@@ -818,6 +845,18 @@ class AmityModuleNotEntitledError extends ASCApiError {
         this.type = 'AmityModuleNotEntitledError';
     }
 }
+/**
+ * Input sanitization related error
+ * @category Errors
+ */
+class ASCInvalidParameterError extends ASCError {
+    /**
+     * @param message A custom error message
+     */
+    constructor(message) {
+        super(message, 800110 /* Amity.ClientError.INVALID_PARAMETERS */, "error" /* Amity.ErrorLevel.ERROR */);
+    }
+}
 
 let activeClient = null;
 /**
@@ -1591,6 +1630,24 @@ const sortByLastUpdated = ({ updatedAt: a = 0 }, { updatedAt: b = 0 }) => new Da
  * Sorting a collection by the items with most recent activity
  */
 const sortByLastActivity = ({ lastActivity: a }, { lastActivity: b }) => new Date(b).valueOf() - new Date(a).valueOf();
+/**
+ * Sorting a channel collection by the time of its newest message (newest first).
+ * Channels whose `lastMessageAt` is `null` sort last, ordered by `createdAt`
+ * (newest first) among themselves, matching the server's `sortBy=lastMessage`
+ * order so the local sort agrees with the page order.
+ */
+const sortByLastMessage = (a, b) => {
+    var _a, _b;
+    const aAt = (_a = a.lastMessageAt) !== null && _a !== void 0 ? _a : null;
+    const bAt = (_b = b.lastMessageAt) !== null && _b !== void 0 ? _b : null;
+    if (aAt !== null && bAt !== null)
+        return new Date(bAt).valueOf() - new Date(aAt).valueOf();
+    if (aAt !== null)
+        return -1;
+    if (bAt !== null)
+        return 1;
+    return new Date(b.createdAt).valueOf() - new Date(a.createdAt).valueOf();
+};
 /**
  * Filter items by untilAt timestamp based on sort direction
  * - For 'lastCreated' (newest first): untilAt acts as lower bound, excludes items older than boundary
@@ -1675,8 +1732,13 @@ const scheduleTask = (task) => {
     clearTimeout(timer);
     tasks.push(task);
     timer = setTimeout(() => {
-        tasks.forEach(fn => fn());
+        // Swap the queue out before running it. A task that schedules another task
+        // while the batch runs (an event handler that fires an event) must land in
+        // a fresh queue and its own timer, not in the array being drained and then
+        // discarded.
+        const batch = tasks;
         tasks = [];
+        batch.forEach(fn => fn());
     }, 0);
 };
 
@@ -8042,6 +8104,140 @@ const postCommentCountEngineOnLoginHandler = () => onSessionStateChange(state =>
     }
 });
 
+const BOTH_FIELDS = { lastActivity: true, lastMessageAt: true };
+/**
+ * The channel cache is keyed by `channelInternalId`, but a message names its
+ * channel by whichever id the producer had: the raw MQTT payload carries the
+ * internal id, a converted `Amity.InternalMessage` carries the public id, and
+ * the optimistic message carries the sub-channel's `channelId`. Try the direct
+ * key first, then match any of the three ids.
+ */
+const findCachedChannel = (channelId) => {
+    var _a, _b, _c;
+    const direct = (_a = pullFromCache(['channel', 'get', channelId])) === null || _a === void 0 ? void 0 : _a.data;
+    if (direct)
+        return direct;
+    return (_c = (_b = queryCache(['channel', 'get'])) === null || _b === void 0 ? void 0 : _b.find(({ data }) => data.channelInternalId === channelId ||
+        data.channelId === channelId ||
+        data.channelPublicId === channelId)) === null || _c === void 0 ? void 0 : _c.data;
+};
+const isNewer = (stored, at) => !stored || convertDateStringToTimestamp(stored) < convertDateStringToTimestamp(at);
+const isSameInstant = (stored, at) => !!stored && convertDateStringToTimestamp(stored) === convertDateStringToTimestamp(at);
+/** Pushes the changed fields in one write and emits one `local.channel.updated`. */
+const commit = (channel, changes) => {
+    if (Object.keys(changes).length === 0)
+        return false;
+    const updated = shallowClone(channel, changes);
+    // Write back under the key the cache actually uses (the resolver key), not
+    // under `channel.channelId`, which can differ from `channelInternalId`.
+    pushToCache(['channel', 'get', getResolver('channel')(updated)], updated);
+    fireEvent('local.channel.updated', {
+        channels: [updated],
+        channelUsers: [],
+        users: [],
+        files: [],
+    });
+    return true;
+};
+/**
+ * Single owner of every local write to a channel's ordering timestamps,
+ * `lastActivity` and `lastMessageAt` (ChannelActivityService v1).
+ *
+ * - Monotonic per field: a field moves only when `at` is newer than the stored
+ *   value (or the stored value is `null`), so a late or replayed event never
+ *   moves a channel down the list.
+ * - One write: both fields are read, compared and pushed in a single cache
+ *   update, followed by one `local.channel.updated` event so every open channel
+ *   collection re-sorts once.
+ * - Server channel payloads never go through here; they overwrite unguarded.
+ *
+ * @returns `true` when at least one field moved
+ * @category private
+ */
+const updateChannelActivityTimestamps = (channelId, at, fields = BOTH_FIELDS) => {
+    const client = getActiveClient();
+    if (!client.cache || !channelId || !at)
+        return false;
+    const channel = findCachedChannel(channelId);
+    if (!channel)
+        return false;
+    const changes = {};
+    if (fields.lastActivity && isNewer(channel.lastActivity, at))
+        changes.lastActivity = at;
+    if (fields.lastMessageAt && isNewer(channel.lastMessageAt, at))
+        changes.lastMessageAt = at;
+    return commit(channel, changes);
+};
+/**
+ * Local correction for the current user's own send (ChannelActivityService v1
+ * REQ-009, Trigger Matrix row 1b). Once the server confirms the message, each
+ * field that still holds the device-clock `localAt` written at send time is
+ * replaced by the server's `serverAt`, even when that is older. A field a newer
+ * message has already moved is left alone. One write, one change notification,
+ * nothing when neither field still holds `localAt`.
+ *
+ * @returns `true` when at least one field was replaced
+ * @category private
+ */
+const confirmOwnMessage = (channelId, localAt, serverAt) => {
+    const client = getActiveClient();
+    if (!client.cache || !channelId || !localAt || !serverAt)
+        return false;
+    if (isSameInstant(localAt, serverAt))
+        return false;
+    const channel = findCachedChannel(channelId);
+    if (!channel)
+        return false;
+    const changes = {};
+    if (isSameInstant(channel.lastActivity, localAt))
+        changes.lastActivity = serverAt;
+    if (isSameInstant(channel.lastMessageAt, localAt))
+        changes.lastMessageAt = serverAt;
+    return commit(channel, changes);
+};
+
+/**
+ * Session-wide owner of the local `lastActivity` / `lastMessageAt` updates
+ * (ChannelActivityService v1, Web migration rows W1 – W5).
+ *
+ * Registered once per session from `setupLoginSubscriptions` and
+ * `resumeSession`, so the update runs whether or not a channel collection is
+ * open, and exactly once per message however many collections are open.
+ *
+ * It listens to the raw events rather than `onMessageCreatedMqtt`, so it does
+ * not duplicate that subscriber's side effects (mark-read, unread recount).
+ *
+ * @category private
+ */
+const channelActivityOnLoginHandler = () => {
+    const client = getActiveClient();
+    const disposers = [
+        // Any user's new message, in any message feed of the channel. The raw
+        // payload's `channelId` is the channel's internal id.
+        createEventSubscriber(client, 'channelActivity', 'message.created', payload => {
+            payload.messages.forEach(message => {
+                updateChannelActivityTimestamps(message.channelId, message.createdAt);
+            });
+        }),
+        // The current user's own send fires this three times: with the optimistic
+        // message at send time (Syncing), on the create response (Synced), and on
+        // failure (Error). The device-clock time of the Syncing / Error fires was
+        // already applied synchronously in createMessageOptimistic, and replaying it
+        // here could undo the server correction made on the response
+        // (confirmOwnMessage). Only the server-confirmed fire goes through the guard.
+        createEventSubscriber(client, 'channelActivity', 'local.message.created', payload => {
+            payload.messages.forEach(message => {
+                if (message.syncState !== "synced" /* Amity.SyncState.Synced */)
+                    return;
+                updateChannelActivityTimestamps(message.channelId, message.createdAt);
+            });
+        }),
+    ];
+    return () => {
+        disposers.forEach(fn => fn());
+    };
+};
+
 const EVENTS = [
     'disconnected',
     'error',
@@ -8231,7 +8427,7 @@ const setupLoginSubscriptions = (unsubWatcher) => {
     // 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(), reactionSyncEngineOnLoginHandler(), blockedUserSyncEngineOnLoginHandler(), blockingUserSyncEngineOnLoginHandler(), blockRealtimeOnLoginHandler(), resetAutoSubscriptionsOnLogout(), CursorController.clearOnLogout(), postCommentCountEngineOnLoginHandler());
+    onChannelDeleted(removeChannelMarkerCache), onChannelMemberBanned(removeChannelMarkerCache), markReadEngineOnLoginHandler(), analyticsEngineOnLoginHandler(), objectResolverEngineOnLoginHandler(), reactionSyncEngineOnLoginHandler(), blockedUserSyncEngineOnLoginHandler(), blockingUserSyncEngineOnLoginHandler(), blockRealtimeOnLoginHandler(), resetAutoSubscriptionsOnLogout(), CursorController.clearOnLogout(), postCommentCountEngineOnLoginHandler(), channelActivityOnLoginHandler());
     if (client.useLegacyUnreadCount) {
         subscriptions.push(readReceiptSyncEngineOnLoginHandler());
     }
@@ -9492,7 +9688,7 @@ const resumeSession = async (params, sessionHandler, config) => {
         // 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());
+        onChannelDeleted(removeChannelMarkerCache), onChannelMemberBanned(removeChannelMarkerCache), markReadEngineOnLoginHandler(), analyticsEngineOnLoginHandler(), objectResolverEngineOnLoginHandler(), channelActivityOnLoginHandler());
         if (client.useLegacyUnreadCount) {
             subscriptions$1.push(readReceiptSyncEngineOnLoginHandler());
         }
@@ -13451,7 +13647,7 @@ const getWatchSessionStorage = () => {
     return storageInstance;
 };
 
-const privateKey = "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDHo80SecH7FuF2\nhFYnb+l26/VN8UMLXAQFLnxciNTEwkGVFMpdezlH8rU2HtUJL4RETogbAOLVY0XM\njs6sPn8G1nALmh9qeDpUtVqFOVtBHxEZ910TLOtQiunjqJKO5nWdqZ71EC3OFluR\niGQkO84BiIFbv37ub7xl3S8XarbtKoLcyVpkDHi+1wx1pgCAn6gtBUgckPL5NR8j\nLseabl3HAXQfhTCKo4tmOFM2Dxwl1IUMmIJrJg/aIU/U0tj/1Eoo7mG0JcNWX19l\nW3EecCbi0ncCJOrkUdwlBrcjaMayaX/ubEwyUeTGiLdyc4L3GRLHjyK8xgVNXRMH\nbZWJ2a5NAgMBAAECggEASxuE+35zTFO/XydKgmvIGcWL9FbgMlXb7Vcf0nBoG945\nbiz0NVc2paraIhJXc608xbYF3qLmtAE1MVBI0ORyRdBHNxY024l/6H6SH60Ed+uI\nM4ysp5ourY6Vj+DLwpdRiI9YDjqYAQDIUmhNxJP7XPhOMoZI6st+xZQBM34ic/bv\nAMSJm9OZphSp3+qXVkFZztr2mxD2EZSJJLYxi8BCdgM2qhazalbcJ6zDKHCZWVWm\n8RRxDGldyMb/237JxETzP40tAlzOZDmBAbUgEnurDJ93RVDIE3rbZUshwgeQd18a\nem096mWgvB1AIKYgsTAR3pw+V19YWAjq/glP6fz8wQKBgQD/oQq+ukKF0PRgBeM5\ngeTjSwsdGppQLmf5ndujvoiz/TpdjDEPu6R8kigQr1rG2t4K/yfdZoI8RdmJD1al\n3Q7N9hofooSy4rj6E3txzWZCHJjHad2cnCp/O26HiReGAl7wTcfTmNdiFHhZQzm5\nJBkvWAiwuvQMNfEbnXxw6/vIDwKBgQDH7fX8gsc77JLvAWgp1MaQN/sbqVb6JeT1\nFQfR8E/WFCSmzQBtNzd5KgYuCeelwr/8DyYytvN2BzCYZXp73gI1jF3YlW5jVn74\nOY6TwQ095digwo6Z0yuxopdIOApKgAkL9PRKgNrqAf3NAyMua6lOGifzjDojC3KU\nfylQmxMn4wKBgHp2B9O/H0dEBw5JQ8W0+JX6yWQz7mEjGiR2/1W+XXb8hQ1zr709\nw1r6Gb+EghRpnZ3fBpYGGbYOMFx8wKHM+N6qW3F0ReX8v2juFGE8aRSa5oYBrWzt\nU16Idjbv8hj84cZ1PJmdyvDtpYn9rpWHOZl4rxEbPvbqkIsOMyNVqdT5AoGAOSge\nmwIIU2le2FVeohbibXiToWTYKMuMmURZ5/r72AgKMmWJKbAPe+Q3wBG01/7FRBpQ\noU8Ma0HC8s6QJbliiEyIx9JwrJWd1vkdecBHONrtA4ibm/5zD2WcOllLF+FitLhi\n3qnX6+6F0IaFGFBPJrTzlv0P4dTz/OAdv52V7GECgYEA2TttOKBAqWllgOaZOkql\nLVMJVmgR7s6tLi1+cEP8ZcapV9aRbRzTAKXm4f8AEhtlG9F9kCOvHYCYGi6JaiWJ\nZkHjeex3T+eE6Di6y5Bm/Ift5jtVhJ4jCVwHOKTMej79NPUFTJfv8hCo29haBDv6\nRXFrv+T21KCcw8k3sJeJWWQ=\n-----END PRIVATE KEY-----";
+const privateKey = "MIIEpQIBAAKCAQEAwAEc/oZgYIvKSUG/C3mONYLR4ZPgAjMEX4bJ+xqqakUDRtqlNO+eZs2blQ1Ko0DBkqPExyQezvjibH5W2UZBV5RaBTlTcNVKTToMBEGesAfaEcM3qUyQHxdbFYZv6P4sb14dcwxTQ8usmaV8ooiR1Fcaso5ZWYcZ8Hb46FbQ7OoVumsBtPWwfZ4f003o5VCl6AIM6lcLv9UDLlFVYhE+PeXpRHtfWlGqxMvqC9oinlwhL6nWv6VjQXW4nhcib72dPBzfHT7k/PMKto2SxALYdb68ENiAGuJLWi3AUHSyYCJK2w7wIlWfJUAI0v26ub10IpExr6D5QuW2577jjP93iwIDAQABAoIBAFWfqXhwIIatkFY+9Z1+ZcbDQimgsmMIsUiQaX6Lk7e0cxOj6czDlxYtVtaPiNtow2pLkjNkjkCqiP7tEHnwdK9DvylZOTa2R15NJpK3WLcTqVIGhsn/FL5owfvFah6zSsmXZParZm5zY9NZE03ALZhOB9/cz0e3kf/EbpfeL2mW7MApyiUt5i09ycchroOpcWp73ipIxvgigtZyUGFmsQicWhUs28F0D7w4Qfk76yG3nqXeb+BAMhCaIaa/k/aAxhiZG/ygEQWQrcC8gfe+jyicMAQPDEVS9YuUMGsLjIjKuVLZzp2xirQnhc2i2zVNEIvG6soprPOBEMQugzrtX5ECgYEA3b7KAbBIbDl1e4ZSCWhHdHkiWVZHaopsR/LhqDDNhXjWjq3AesgV6k0j9EdziMn/HmmOso0bz99GTV3JZf4A9ztTLumJlkHbdVtlgOqSjrFLj12rH9KXTheyIhWSpUmm8+WB1xasFbqpvJaGo7F3pd2Fqj1XR4mp5BO7c/t7LJ0CgYEA3aouEzXQ9THRKYocdfY69EI1Il1t/d/RSqqd9BxEjxBgxkM13ZiYIn/R4WW/nCUrlmhxG44Aa2Gob4Ahfsui2xKTg/g/3Zk/rAxAEGkfOLGoenaJMD41fH4wUq3FRYwkvnaMb9Hd6f/TlBHslIRa2NN58bSBGJCyBP2b59+2+EcCgYEAixDVRXvV37GlYUOa/XVdosk5Zoe6oDGRuQm0xbNdoUBoZvDHDvme7ONWEiQha/8qtVsD+CyQ7awcPfb8kK9c0bBt+bTS6d4BkTcxkEkMgtrkBVR8Nqfu5jXsLH4VCv4G61zbMhZw8+ut+az5YX2yCN7Frj9sFlxapMRPQmzMEe0CgYEAumsAzM8ZqNv4mAK65Mnr0rhLj1cbxcKRdUYACOgtEFQpzxN/HZnTeFAe5nx3pI3uFlRHq3DFEYnT6dHMWaJQmAULYpVIwMi9L6gtyJ9fzoI6uqMtxRDMUqKdaSsTGOY/kJ6KhQ/unXi1K3XXjR+yd1+C0q+HUm1+CYxvrZYLfskCgYEArsEy+IQOiqniJ0NE2vVUF+UK/IRZaic9YKcpov5Ot7Vvzm/MnnW4N1ljVskocETBWMmPUvNSExVjPebi+rxd8fa5kY8BJScPTzMFbunZn/wjtGdcM10qdlVQ9doG61A/9P3ezFKCfS4AvF/H/59LcSx2Bh28fp3/efiVIOpVd4Y=";
 /*
  * The crypto algorithm used for importing key and signing string
  */
@@ -15250,18 +15446,18 @@ const buildFlagUserBody = (options) => {
 /**
  * ```js
  * import { UserRepository } from '@amityco/ts-sdk'
+ *
+ * // Typeless report (supported).
  * const flagged = await UserRepository.flagUser('userId')
- * const flaggedBehavior = await UserRepository.flagUser('userId', {
- *   reportType: 'behavior',
- *   reason: 'Harassment or bullying',
- *   comment: 'optional free-text',
- * })
  * ```
  *
+ * Flags a user. Two call shapes are accepted (see the overloads): id-only, which
+ * sends no body and stays supported, and the deprecated structured options object,
+ * whose request mapping is unchanged. New code reporting a profile field or behavior
+ * should use `flagUserProfile` or `flagUserBehavior`.
+ *
  * @param userId The ID of the user to be flagged
- * @param options Optional report metadata forwarded to the server as the request
- *   body: `reportType`, `reason`, `comment`. Only non-null fields are included.
- *   All validation is server-side; a bodyless call produces a typeless report.
+ * @param options Deprecated report metadata; omit for a typeless report
  * @returns the flagged {@link Amity.User}
  *
  * @category User API
@@ -15282,25 +15478,224 @@ const flagUser = async (userId, options) => {
 };
 /* end_public_function */
 
+/**
+ * Sends a validated split user report (`flagUserProfile` / `flagUserBehavior`) to the
+ * same endpoint as `flagUser`, then persists the returned user and fires `user.flagged`
+ * exactly as `flagUser` does, so all three calls share return, cache and event behaviour.
+ *
+ * Not exported from the public API.
+ */
+const submitUserReport = async (apiName, userId, body) => {
+    var _a;
+    const client = getActiveClient();
+    client.log(`user/${apiName}`, { userId, body });
+    const { data } = await client.http.post(`/api/v4/me/flags/${encodeURIComponent(userId)}`, body);
+    const payload = prepareUserPayload(data);
+    if (client.cache) {
+        ingestInCache(payload);
+    }
+    fireEvent('user.flagged', data);
+    return (_a = payload.users.find(user => user.userId === userId)) !== null && _a !== void 0 ? _a : payload.users[0];
+};
+
+/** Maximum `comment` length, in string length units, after trimming. */
+const USER_REPORT_COMMENT_MAX_LENGTH = 300;
+const PROFILE_FIELDS = Object.values(UserProfileFieldEnum);
+const BEHAVIOR_REASONS = Object.values(ContentFlagReasonEnum);
+const REPORT_TYPE_FILTERS = Object.values(UserReportTypeFilterEnum);
+const assertOptionsObject = (apiName, options, shape) => {
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+        throw new ASCInvalidParameterError(`${apiName}: expected an options object \`${shape}\``);
+    }
+    return options;
+};
+/**
+ * Normalizes an optional reporter `comment`: it must be a string when supplied (`null`
+ * is not a valid supplied comment); it is trimmed; a blank result is omitted (the
+ * backend rejects `""`); a result longer than 300 characters is rejected before any
+ * request. Otherwise the trimmed text is returned unchanged.
+ *
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` for a non-string or over-length comment
+ */
+const normalizeUserReportComment = (apiName, comment) => {
+    if (comment === undefined)
+        return undefined;
+    if (typeof comment !== 'string') {
+        throw new ASCInvalidParameterError(`${apiName}: \`comment\` must be a string when supplied`);
+    }
+    const trimmed = comment.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.length > USER_REPORT_COMMENT_MAX_LENGTH) {
+        throw new ASCInvalidParameterError(`${apiName}: \`comment\` must be at most ${USER_REPORT_COMMENT_MAX_LENGTH} characters after trimming`);
+    }
+    return trimmed;
+};
+const withComment = (body, comment) => comment === undefined ? body : Object.assign(Object.assign({}, body), { comment });
+/**
+ * Validates `flagUserProfile` options and builds its request body. Untyped callers can
+ * pass anything at runtime, so nothing is trusted from the declared type. Any `reason`
+ * key is ignored and never sent.
+ *
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when the options are malformed
+ */
+const toUserProfileReportBody = (options) => {
+    const apiName = 'flagUserProfile';
+    const { field, comment } = assertOptionsObject(apiName, options, '{ field, comment? }');
+    if (typeof field !== 'string' || !PROFILE_FIELDS.includes(field)) {
+        throw new ASCInvalidParameterError(`${apiName}: \`field\` must be a \`UserProfileFieldEnum\` value`);
+    }
+    return withComment({ reportType: field }, normalizeUserReportComment(apiName, comment));
+};
+/**
+ * Validates `flagUserBehavior` options and builds its request body. `reason` must be one
+ * of the nine `ContentFlagReasonEnum` values and is sent as that canonical label;
+ * `reportType` is always `behavior`.
+ *
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when the options are malformed
+ */
+const toUserBehaviorReportBody = (options) => {
+    const apiName = 'flagUserBehavior';
+    const { reason, comment } = assertOptionsObject(apiName, options, '{ reason, comment? }');
+    if (typeof reason !== 'string' || !BEHAVIOR_REASONS.includes(reason)) {
+        throw new ASCInvalidParameterError(`${apiName}: \`reason\` must be a \`ContentFlagReasonEnum\` value`);
+    }
+    return withComment({ reportType: 'behavior', reason }, normalizeUserReportComment(apiName, comment));
+};
+/**
+ * Validates the optional `{ reportType? }` of `unflagUser` and builds its query parameters.
+ * Returns `undefined` when no `reportType` is given, so the request carries no query string
+ * and withdraws every report the caller filed on the user. The server validates the value
+ * too (422); this local check only saves the round-trip for the string alias, which admits
+ * raw strings. Untyped callers can pass anything at runtime, so nothing is trusted from the
+ * declared type.
+ *
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when the options are malformed or `reportType` is unknown
+ */
+const toUserReportTypeFilter = (options) => {
+    if (options === undefined)
+        return undefined;
+    const apiName = 'unflagUser';
+    const { reportType } = assertOptionsObject(apiName, options, '{ reportType? }');
+    if (reportType === undefined)
+        return undefined;
+    if (typeof reportType !== 'string' || !REPORT_TYPE_FILTERS.includes(reportType)) {
+        throw new ASCInvalidParameterError(`${apiName}: \`reportType\` must be a \`UserReportTypeFilterEnum\` value`);
+    }
+    return { reportType: reportType };
+};
+
+/* begin_public_function
+  id: user.flag_profile
+*/
+/**
+ * ```js
+ * import { UserRepository, UserProfileFieldEnum } from '@amityco/ts-sdk'
+ * const flagged = await UserRepository.flagUserProfile('userId', {
+ *   field: UserProfileFieldEnum.AVATAR,
+ *   comment: 'Nudity in profile photo',
+ * })
+ * ```
+ *
+ * Reports one of a user's profile fields (display name, description or avatar). The
+ * call has no reason: profile reports never carry one, so the backend's reason rules
+ * cannot be violated from here. A `reason` key passed at runtime is ignored and never sent.
+ *
+ * `comment` is trimmed; a blank comment is omitted from the request; a comment longer
+ * than 300 characters after trimming is rejected before any request. Otherwise the
+ * trimmed text is sent unchanged.
+ *
+ * Sends `POST /api/v4/me/flags/:userId` with `{ reportType: <field>, comment? }`.
+ *
+ * @param userId The ID of the user to be reported
+ * @param options `field` is a `UserProfileFieldEnum` value; `comment` is optional free text
+ * @returns the flagged {@link Amity.User}
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when `options` is missing or malformed, or `comment` is over 300 characters, before any request is made
+ *
+ * @category User API
+ * @async
+ * */
+const flagUserProfile = async (userId, options) => submitUserReport('flagUserProfile', userId, toUserProfileReportBody(options));
+/* end_public_function */
+
+/* begin_public_function
+  id: user.flag_behavior
+*/
+/**
+ * ```js
+ * import { UserRepository, ContentFlagReasonEnum } from '@amityco/ts-sdk'
+ * const flagged = await UserRepository.flagUserBehavior('userId', {
+ *   reason: ContentFlagReasonEnum.Others,
+ *   comment: 'Impersonating our brand',
+ * })
+ * ```
+ *
+ * Reports a user's behavior. `reason` is required and is one of the nine
+ * `ContentFlagReasonEnum` values, sent as its canonical label. Reporter text, including
+ * the explanation for `Others`, always travels in `comment`; the reason never carries text.
+ *
+ * `comment` is trimmed; a blank comment is omitted from the request; a comment longer
+ * than 300 characters after trimming is rejected before any request. Otherwise the
+ * trimmed text is sent unchanged.
+ *
+ * Sends `POST /api/v4/me/flags/:userId` with `{ reportType: 'behavior', reason, comment? }`.
+ *
+ * @param userId The ID of the user to be reported
+ * @param options `reason` is a `ContentFlagReasonEnum` value; `comment` is optional free text
+ * @returns the flagged {@link Amity.User}
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when `options` is missing or malformed, `reason` is missing or unknown, or `comment` is over 300 characters, before any request is made
+ *
+ * @category User API
+ * @async
+ * */
+const flagUserBehavior = async (userId, options) => submitUserReport('flagUserBehavior', userId, toUserBehaviorReportBody(options));
+/* end_public_function */
+
 /* begin_public_function
   id: user.unflag
 */
 /**
  * ```js
- * import { UserRepository } from '@amityco/ts-sdk'
- * const unflagged = await UserRepository.unflagUser('post', postId)
+ * import { UserRepository, UserReportTypeFilterEnum } from '@amityco/ts-sdk'
+ *
+ * // Withdraw every report I filed on the user.
+ * const unflagged = await UserRepository.unflagUser('userId')
+ *
+ * // Withdraw only my behavior report; my other reports on the user stay.
+ * await UserRepository.unflagUser('userId', { reportType: UserReportTypeFilterEnum.BEHAVIOR })
+ *
+ * // Withdraw only my typeless (legacy) report.
+ * await UserRepository.unflagUser('userId', { reportType: UserReportTypeFilterEnum.UNTYPED })
  * ```
  *
+ * Withdraws the caller's reports on a user. Without `reportType` every report the caller
+ * filed on that user is withdrawn, as before. With `reportType` only the caller's report
+ * of that type is withdrawn; the caller's other reports and other users' reports are
+ * untouched. Withdrawing a report that does not exist succeeds and changes nothing.
+ *
+ * The returned user is persisted to the cache, so its `hashFlag` says whether the caller
+ * still holds any report on the user. Do not flip a local "flagged by me" flag to `false`
+ * after a per-type withdrawal; read the fresh user, or call `isUserFlaggedByMe` for the
+ * remaining per-type state (`flags`).
+ *
+ * Sends `DELETE /api/v4/me/flags/:userId`, with `?reportType=<type>` when one is given.
+ *
  * @param userId The ID of the user to unflag
- * @returns the deleted report result
+ * @param options Optional; `reportType` selects a single report to withdraw. For a report that `isUserFlaggedByMe` lists with `reportType: null`, pass `UserReportTypeFilterEnum.UNTYPED`
+ * @returns `true` once the server has processed the withdrawal
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when `reportType` is not a `UserReportTypeFilterEnum` value, before any request is made
  *
  * @category User API
  * @async
  * */
-const unflagUser = async (userId) => {
-    const client = getActiveClient();
-    client.log('user/unflag', userId);
-    const { data } = await client.http.delete(`/api/v4/me/flags/${encodeURIComponent(userId)}`);
+const unflagUser = async (userId, options) => {
+    const client = getActiveClient();
+    client.log('user/unflag', { userId, options });
+    const params = toUserReportTypeFilter(options);
+    const url = `/api/v4/me/flags/${encodeURIComponent(userId)}`;
+    const { data } = params
+        ? await client.http.delete(url, { params })
+        : await client.http.delete(url);
     const payload = prepareUserPayload(data);
     if (client.cache) {
         ingestInCache(payload);
@@ -15316,11 +15711,29 @@ const unflagUser = async (userId) => {
 /**
  * ```js
  * import { UserRepository } from '@amityco/ts-sdk'
- * const isFlagged = await UserRepository.isUserFlaggedByMe(postId)
+ *
+ * const { isFlagByMe, flags } = await UserRepository.isUserFlaggedByMe('userId')
+ *
+ * // Grey out the report options already used; null marks the typeless report.
+ * const used = new Set(flags.map(flag => flag.reportType))
  * ```
  *
- * @param userId The ID of the thing to check a report to.
- * @returns `true` if the report is created by me, `false` if doesn't.
+ * Returns whether the caller has reported a user, with each of the caller's own reports
+ * on that user, exactly as `GET /api/v4/users/:userId/isFlagByMe` answers. Each report
+ * carries `reportType`, `reason`, `comment` and `createdAt`; a field the report does not
+ * have is `null`. `reportType: null` is the typeless (legacy) report, which `unflagUser`
+ * withdraws with `UserReportTypeFilterEnum.UNTYPED`. Only the caller's reports come back.
+ *
+ * This is the only source of per-type state. Nothing is filtered, cached or persisted:
+ * the call reads the server every time and does not consult `hashFlag`, which is a
+ * type-blind bloom filter. Call it again after a flag or unflag when the UI needs the
+ * updated per-type state.
+ *
+ * Breaking change: earlier versions returned a boolean from the v3 endpoint, which the
+ * backend has deprecated. Read `isFlagByMe` on the result for the same answer.
+ *
+ * @param userId The ID of the user to check
+ * @returns the caller's {@link Amity.UserFlagByMe} on that user
  *
  * @category Report API
  * @async
@@ -15328,8 +15741,8 @@ const unflagUser = async (userId) => {
 const isUserFlaggedByMe = async (userId) => {
     const client = getActiveClient();
     client.log('user/isUserFlaggedByMe', userId);
-    const { data: { isFlagByMe }, } = await client.http.get(`/api/v3/users/${userId}/isFlagByMe`);
-    return isFlagByMe;
+    const { data } = await client.http.get(`/api/v4/users/${encodeURIComponent(userId)}/isFlagByMe`);
+    return data;
 };
 /* end_public_function */
 
@@ -16456,6 +16869,8 @@ var index$r = /*#__PURE__*/Object.freeze({
     getUserByIds: getUserByIds,
     updateUser: updateUser,
     flagUser: flagUser,
+    flagUserProfile: flagUserProfile,
+    flagUserBehavior: flagUserBehavior,
     unflagUser: unflagUser,
     isUserFlaggedByMe: isUserFlaggedByMe,
     getAllBlockedUsers: getAllBlockedUsers,
@@ -18877,7 +19292,8 @@ const getPostReport = async ({ client, referenceId, }) => {
 };
 const getUserReport = async ({ client, referenceId, }) => {
     var _a;
-    const { data } = await client.http.get(`/api/v3/users/${referenceId}/isflagbyme`);
+    // v3 isFlagByMe is deprecated by the backend; v4 answers the same boolean plus the caller's flags.
+    const { data } = await client.http.get(`/api/v4/users/${encodeURIComponent(referenceId)}/isFlagByMe`);
     const { result, isFlagByMe } = data !== null && data !== void 0 ? data : {};
     return (_a = result !== null && result !== void 0 ? result : isFlagByMe) !== null && _a !== void 0 ? _a : false;
 };
@@ -19494,7 +19910,7 @@ const getLocalId = () => `LOCAL_${uuid()}`;
 // FIXME: temp solution
 let uniqueId;
 const createMessageOptimistic = (bundle) => {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const client = getActiveClient();
     if (!client.cache)
         return;
@@ -19525,9 +19941,20 @@ const createMessageOptimistic = (bundle) => {
     }
     // as reused to update created and updated time, which should be the same
     const createdTime = new Date().toISOString();
-    const message = Object.assign({ creatorId: client.userId, creatorPrivateId: getActiveUser()._id, channelSegment: ((_b = subChannel === null || subChannel === void 0 ? void 0 : subChannel.data.messageCount) !== null && _b !== void 0 ? _b : 0) + 1, childrenNumber: 0, createdAt: createdTime, updatedAt: createdTime, syncState: "syncing" /* Amity.SyncState.Syncing */, isDeleted: false }, bundleWithMessageId);
+    const message = Object.assign({ 
+        // The optimistic message must name its channel (public id) so the own-send
+        // update can move lastActivity / lastMessageAt at send time. Take it from the
+        // cached sub-channel; when that is not cached, resolve the sub-channel id
+        // through the channel cache, which for a channel's default sub-channel is
+        // the channel itself (ChannelActivityService migration row I2). A thread or
+        // unknown channel resolves to undefined, as before.
+        channelId: (_b = subChannel === null || subChannel === void 0 ? void 0 : subChannel.data.channelId) !== null && _b !== void 0 ? _b : (_c = findCachedChannel(bundle.subChannelId)) === null || _c === void 0 ? void 0 : _c.channelId, creatorId: client.userId, creatorPrivateId: getActiveUser()._id, channelSegment: ((_d = subChannel === null || subChannel === void 0 ? void 0 : subChannel.data.messageCount) !== null && _d !== void 0 ? _d : 0) + 1, childrenNumber: 0, createdAt: createdTime, updatedAt: createdTime, syncState: "syncing" /* Amity.SyncState.Syncing */, isDeleted: false }, bundleWithMessageId);
     const cachedAt = UNSYNCED_OBJECT_CACHED_AT_VALUE;
     pushToCache(['message', 'get', message.messageId], message, { cachedAt });
+    // Own-send update (ChannelActivityService row 1): move the channel at send
+    // time, synchronously, so the confirmation on the send response always sees
+    // this value rather than racing the scheduled local event below.
+    updateChannelActivityTimestamps(message.channelId, message.createdAt);
     fireEvent('local.message.created', { messages: [message] });
     return message;
 };
@@ -19567,6 +19994,9 @@ const createMessage = async (bundle) => {
         if (client.cache) {
             ingestInCache(data, { cachedAt });
         }
+        // The own-send update wrote the device-clock createdAt; replace it with the
+        // server's now that the message is confirmed (ChannelActivityService REQ-009).
+        confirmOwnMessage(optimisticData === null || optimisticData === void 0 ? void 0 : optimisticData.channelId, optimisticData === null || optimisticData === void 0 ? void 0 : optimisticData.createdAt, messages[0].createdAt);
         fireEvent('local.message.created', {
             messages: [Object.assign(Object.assign({}, messages[0]), { syncState: "synced" /* Amity.SyncState.Synced */ })],
         });
@@ -20160,23 +20590,85 @@ getDeliveredUsers.locally = (query) => {
     return { data: users, cachedAt, prevPage, nextPage };
 };
 
-/* begin_public_function
-  id: message.flag
-*/
+const CONTENT_FLAG_REASONS = Object.values(ContentFlagReasonEnum);
 /**
- * ```js
- * import { MessageRepository } from '@amityco/ts-sdk'
- * const flagged = await MessageRepository.flagMessage(messageId, reason)
- * ```
+ * True when a public `flagX(id, input)` argument is the legacy shape (a reason string
+ * or nothing). Anything else is routed to the `Amity.ContentFlagOptions` path, whose
+ * validation rejects malformed values before any request is made.
+ */
+const isLegacyContentFlagReason = (input) => input === undefined || typeof input === 'string';
+/**
+ * Validates an `Amity.ContentFlagOptions` argument. Untyped (plain JS) callers can pass
+ * anything at runtime, so the checks do not trust the declared type: the value must be a
+ * plain object, `reason` must be one of the nine `ContentFlagReasonEnum` values and
+ * `detail`, when supplied, must be a string (`null` is not a valid supplied detail).
  *
- * @param messageId of the message to flag
- * @param reason the reason to flag the message
- * @returns the created report result
+ * @param apiName used in the error message, e.g. `flagPost`
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when the options are malformed
+ */
+const validateContentFlagOptions = (apiName, options) => {
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+        throw new ASCInvalidParameterError(`${apiName}: expected an options object \`{ reason, detail? }\``);
+    }
+    const { reason, detail } = options;
+    if (typeof reason !== 'string' || !CONTENT_FLAG_REASONS.includes(reason)) {
+        throw new ASCInvalidParameterError(`${apiName}: \`reason\` must be a \`ContentFlagReasonEnum\` value`);
+    }
+    if (detail !== undefined && typeof detail !== 'string') {
+        throw new ASCInvalidParameterError(`${apiName}: \`detail\` must be a string when supplied`);
+    }
+    return { reason: reason, detail };
+};
+/**
+ * Builds the request body for validated options. `detail` is forwarded unchanged (empty
+ * and whitespace-only strings included) and omitted from the body when `undefined`; the
+ * backend enforces the 300-character limit.
+ */
+const toContentFlagBody = ({ reason, detail }) => detail === undefined ? { reason } : { reason, detail };
+
+/**
+ * New `flagMessage(messageId, { reason, detail? })` implementation. Any category,
+ * including `Others`, may carry a `detail`. `detail` is forwarded unchanged (empty and
+ * whitespace-only strings included) and omitted from the request body when `undefined`;
+ * the backend enforces the 300-character limit.
  *
- * @category Message API
- * @async
- * */
-const flagMessage = async (messageId, reason) => {
+ * Not exported from the public API. It is reached through the
+ * `MessageRepository.flagMessage(messageId, options)` overload; see `api/flagMessage.ts`.
+ *
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when `options` is malformed, before any request is made
+ */
+const flagMessageWithOptions = async (messageId, options) => {
+    // Validate first: an input error must surface as INVALID_PARAMETERS regardless of
+    // whether a client is active, and validation needs nothing from the client.
+    const body = toContentFlagBody(validateContentFlagOptions('flagMessage', options));
+    const client = getActiveClient();
+    client.log('message/flag', messageId);
+    const { data: payload } = await client.http.post(`/api/v5/messages/${encodeURIComponent(messageId)}/flags`, body);
+    if (client.cache) {
+        const messagePayload = await prepareMessagePayload(payload);
+        ingestInCache(messagePayload);
+    }
+    fireEvent('message.flagged', payload);
+    return !!payload;
+};
+
+/**
+ * Legacy `flagMessage(messageId, reason?)` implementation, kept verbatim so existing
+ * callers keep the exact request body they had before the options contract existed:
+ *
+ * - predefined `ContentFlagReasonEnum` value → `{ reason: <value>, detail: '' }`
+ * - any other non-empty string (including the literal `'Others'`) → `{ reason: 'Others', detail: <string> }`
+ * - `undefined` or `''` → `{ reason: 'Others', detail: '' }`
+ *   (for `undefined` the message body carries `detail: undefined`, which JSON serialization omits)
+ *
+ * Not exported from the public API. It is reached through the deprecated
+ * `MessageRepository.flagMessage(messageId, reason)` overload; see `api/flagMessage.ts`.
+ *
+ * Not itself deprecated: it implements the deprecated legacy-string overload of the public
+ * `flagMessage`, which carries the deprecation tag. New code should use `flagMessageWithOptions`
+ * (the `{ reason, detail? }` contract). This path stays available throughout the current major version.
+ */
+const flagMessageWithReasonString = async (messageId, reason) => {
     const client = getActiveClient();
     client.log('message/flag', messageId);
     const isPredefinedReason = reason &&
@@ -20193,6 +20685,42 @@ const flagMessage = async (messageId, reason) => {
     fireEvent('message.flagged', payload);
     return !!payload;
 };
+
+/* begin_public_function
+  id: message.flag
+*/
+/**
+ * ```js
+ * import { MessageRepository, ContentFlagReasonEnum } from '@amityco/ts-sdk'
+ *
+ * // No reason.
+ * await MessageRepository.flagMessage(messageId)
+ *
+ * // Category plus optional reporter context (any category, including Others).
+ * await MessageRepository.flagMessage(messageId, {
+ *   reason: ContentFlagReasonEnum.SpamOrScams,
+ *   detail: 'Repeated promotional links',
+ * })
+ * ```
+ *
+ * Reports a message to moderation. Three call shapes are accepted (see the overloads):
+ * id-only, an options object, and the deprecated legacy reason string. The public
+ * name only dispatches on the input shape; the two implementations are kept separate
+ * so the legacy path is untouched by the new contract:
+ *
+ * - `undefined` or a string → `flagMessageWithReasonString` (unchanged legacy mapping)
+ * - anything else → `flagMessageWithOptions` (validated `{ reason, detail? }`)
+ *
+ * @param messageId The ID of the message to flag
+ * @param input an options object `{ reason, detail? }`, a legacy reason string, or nothing
+ * @returns `true` when the report was created
+ *
+ * @category Message API
+ * @async
+ * */
+const flagMessage = (messageId, input) => isLegacyContentFlagReason(input)
+    ? flagMessageWithReasonString(messageId, input)
+    : flagMessageWithOptions(messageId, input);
 /* end_public_function */
 
 /* begin_public_function
@@ -21912,6 +22440,9 @@ class ChannelLiveCollectionController extends LiveCollectionController {
             case 'lastCreated':
                 channels = channels.sort(sortByLastCreated);
                 break;
+            case 'lastMessage':
+                channels = channels.sort(sortByLastMessage);
+                break;
             case 'displayName':
                 /*
                  * The server returns channels with empty | null displayName's first before
@@ -21972,9 +22503,8 @@ class ChannelLiveCollectionController extends LiveCollectionController {
                             objectResolverEngine.resolve(message.channelId, "channel" /* Amity.ReferenceType.CHANNEL */);
                         }
                         else {
-                            updateChannelCache(channelCache, {
-                                lastActivity: message.createdAt,
-                            });
+                            // lastActivity / lastMessageAt are moved by channelActivityOnLoginHandler
+                            // (session-wide, monotonic, one write). This listener only re-sorts.
                             callback(message);
                         }
                     });
@@ -21992,9 +22522,7 @@ class ChannelLiveCollectionController extends LiveCollectionController {
                         ])) === null || _a === void 0 ? void 0 : _a.data;
                         if (!cacheData)
                             return;
-                        updateChannelCache(cacheData, {
-                            lastActivity: message.createdAt,
-                        });
+                        // Timestamps are moved by channelActivityOnLoginHandler; only re-sort here.
                         callback(message);
                     });
                 }, 'channelId', 'channel'),
@@ -22732,9 +23260,7 @@ class SearchChannelLiveCollectionController extends LiveCollectionController {
                         ])) === null || _a === void 0 ? void 0 : _a.data;
                         if (!cacheData)
                             return;
-                        updateChannelCache(cacheData, {
-                            lastActivity: message.createdAt,
-                        });
+                        // Timestamps are moved by channelActivityOnLoginHandler; only re-sort here.
                         callback(message);
                     });
                 }, 'channelId', 'channel'),
@@ -22751,9 +23277,7 @@ class SearchChannelLiveCollectionController extends LiveCollectionController {
                         ])) === null || _a === void 0 ? void 0 : _a.data;
                         if (!cacheData)
                             return;
-                        updateChannelCache(cacheData, {
-                            lastActivity: message.createdAt,
-                        });
+                        // Timestamps are moved by channelActivityOnLoginHandler; only re-sort here.
                         callback(message);
                     });
                 }, 'channelId', 'channel'),
@@ -27338,23 +27862,22 @@ const declineComment = async (commentId, reason) => {
 };
 /* end_public_function */
 
-/* begin_public_function
-  id: comment.flag
-*/
 /**
- * ```js
- * import { CommentRepository } from '@amityco/ts-sdk'
- * const flagged = await CommentRepository.flagComment(commentId, reason)
- * ```
+ * Legacy `flagComment(commentId, reason?)` implementation, kept verbatim so existing
+ * callers keep the exact request body they had before the options contract existed:
  *
- * @param commentId The ID of the comment to flag
- * @param reason the reason to flag the comment
- * @returns the created report result
+ * - predefined `ContentFlagReasonEnum` value → `{ reason: <value>, detail: '' }`
+ * - any other non-empty string (including the literal `'Others'`) → `{ reason: 'Others', detail: <string> }`
+ * - `undefined` or `''` → `{ reason: 'Others', detail: '' }`
  *
- * @category Comment API
- * @async
- * */
-const flagComment = async (commentId, reason) => {
+ * Not exported from the public API. It is reached through the deprecated
+ * `CommentRepository.flagComment(commentId, reason)` overload; see `api/flagComment.ts`.
+ *
+ * Not itself deprecated: it implements the deprecated legacy-string overload of the public
+ * `flagComment`, which carries the deprecation tag. New code should use `flagCommentWithOptions`
+ * (the `{ reason, detail? }` contract). This path stays available throughout the current major version.
+ */
+const flagCommentWithReasonString = async (commentId, reason) => {
     const client = getActiveClient();
     client.log('comment/flagComment', commentId);
     const isPredefinedReason = reason &&
@@ -27370,6 +27893,67 @@ const flagComment = async (commentId, reason) => {
     fireEvent('comment.flagged', payload);
     return !!payload;
 };
+
+/**
+ * New `flagComment(commentId, { reason, detail? })` implementation. Any category,
+ * including `Others`, may carry a `detail`. `detail` is forwarded unchanged (empty and
+ * whitespace-only strings included) and omitted from the request body when `undefined`;
+ * the backend enforces the 300-character limit.
+ *
+ * Not exported from the public API. It is reached through the
+ * `CommentRepository.flagComment(commentId, options)` overload; see `api/flagComment.ts`.
+ *
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when `options` is malformed, before any request is made
+ */
+const flagCommentWithOptions = async (commentId, options) => {
+    // Validate first: an input error must surface as INVALID_PARAMETERS regardless of
+    // whether a client is active, and validation needs nothing from the client.
+    const body = toContentFlagBody(validateContentFlagOptions('flagComment', options));
+    const client = getActiveClient();
+    client.log('comment/flagComment', commentId);
+    const { data: payload } = await client.http.post(`/api/v3/comments/${encodeURIComponent(commentId)}/flag`, body);
+    if (client.cache) {
+        ingestInCache(payload);
+    }
+    fireEvent('comment.flagged', payload);
+    return !!payload;
+};
+
+/* 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',
+ * })
+ * ```
+ *
+ * Reports a comment to moderation. Three call shapes are accepted (see the overloads):
+ * id-only, an options object, and the deprecated legacy reason string. The public
+ * name only dispatches on the input shape; the two implementations are kept separate
+ * so the legacy path is untouched by the new contract:
+ *
+ * - `undefined` or a string → `flagCommentWithReasonString` (unchanged legacy mapping)
+ * - anything else → `flagCommentWithOptions` (validated `{ reason, detail? }`)
+ *
+ * @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
+ *
+ * @category Comment API
+ * @async
+ * */
+const flagComment = (commentId, input) => isLegacyContentFlagReason(input)
+    ? flagCommentWithReasonString(commentId, input)
+    : flagCommentWithOptions(commentId, input);
 /* end_public_function */
 
 /* begin_public_function
@@ -29723,23 +30307,47 @@ const declinePost = async (postId) => {
 };
 /* end_public_function */
 
-/* begin_public_function
-  id: post.flag
-*/
 /**
- * ```js
- * import { PostRepository } from '@amityco/ts-sdk'
- * const flagged = await PostRepository.flagPost(postId, reason)
- * ```
+ * New `flagPost(postId, { reason, detail? })` implementation. Any category, including
+ * `Others`, may carry a `detail`. `detail` is forwarded unchanged (empty and
+ * whitespace-only strings included) and omitted from the request body when `undefined`;
+ * the backend enforces the 300-character limit.
  *
- * @param postId of the post to flag
- * @param reason the reason to flag the post
- * @returns a boolean
+ * Not exported from the public API. It is reached through the
+ * `PostRepository.flagPost(postId, options)` overload; see `api/flagPost.ts`.
  *
- * @category Post API
- * @async
- * */
-const flagPost = async (postId, reason) => {
+ * @throws {ASCInvalidParameterError} `INVALID_PARAMETERS` when `options` is malformed, before any request is made
+ */
+const flagPostWithOptions = async (postId, options) => {
+    // Validate first: an input error must surface as INVALID_PARAMETERS regardless of
+    // whether a client is active, and validation needs nothing from the client.
+    const body = toContentFlagBody(validateContentFlagOptions('flagPost', options));
+    const client = getActiveClient();
+    client.log('post/flagPost', postId);
+    const { data: payload } = await client.http.post(`/api/v3/posts/${encodeURIComponent(postId)}/flag`, body);
+    if (client.cache) {
+        ingestInCache(prepareMembershipPayload(payload, 'communityUsers'));
+    }
+    fireEvent('post.flagged', payload);
+    return !!payload;
+};
+
+/**
+ * Legacy `flagPost(postId, reason?)` implementation, kept verbatim so existing
+ * callers keep the exact request body they had before the options contract existed:
+ *
+ * - predefined `ContentFlagReasonEnum` value → `{ reason: <value>, detail: '' }`
+ * - any other non-empty string (including the literal `'Others'`) → `{ reason: 'Others', detail: <string> }`
+ * - `undefined` or `''` → `{ reason: 'Others', detail: '' }`
+ *
+ * Not exported from the public API. It is reached through the deprecated
+ * `PostRepository.flagPost(postId, reason)` overload; see `api/flagPost.ts`.
+ *
+ * Not itself deprecated: it implements the deprecated legacy-string overload of the public
+ * `flagPost`, which carries the deprecation tag. New code should use `flagPostWithOptions`
+ * (the `{ reason, detail? }` contract). This path stays available throughout the current major version.
+ */
+const flagPostWithReasonString = async (postId, reason) => {
     const client = getActiveClient();
     client.log('post/flagPost', postId);
     const isPredefinedReason = reason &&
@@ -29755,6 +30363,42 @@ const flagPost = async (postId, reason) => {
     fireEvent('post.flagged', payload);
     return !!payload;
 };
+
+/* begin_public_function
+  id: post.flag
+*/
+/**
+ * ```js
+ * import { PostRepository, ContentFlagReasonEnum } from '@amityco/ts-sdk'
+ *
+ * // No reason.
+ * await PostRepository.flagPost(postId)
+ *
+ * // Category plus optional reporter context (any category, including Others).
+ * await PostRepository.flagPost(postId, {
+ *   reason: ContentFlagReasonEnum.SpamOrScams,
+ *   detail: 'Repeated promotional links',
+ * })
+ * ```
+ *
+ * Reports a post to moderation. Three call shapes are accepted (see the overloads):
+ * id-only, an options object, and the deprecated legacy reason string. The public
+ * name only dispatches on the input shape; the two implementations are kept separate
+ * so the legacy path is untouched by the new contract:
+ *
+ * - `undefined` or a string → `flagPostWithReasonString` (unchanged legacy mapping)
+ * - anything else → `flagPostWithOptions` (validated `{ reason, detail? }`)
+ *
+ * @param postId The ID of the post to flag
+ * @param input an options object `{ reason, detail? }`, a legacy reason string, or nothing
+ * @returns `true` when the report was created
+ *
+ * @category Post API
+ * @async
+ * */
+const flagPost = (postId, input) => isLegacyContentFlagReason(input)
+    ? flagPostWithReasonString(postId, input)
+    : flagPostWithOptions(postId, input);
 /* end_public_function */
 
 /* begin_public_function
@@ -37135,4 +37779,4 @@ class AmityAttachmentProductTags {
     }
 }
 
-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 };
+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, UserProfileFieldEnum, UserReportTypeEnum, UserReportTypeFilterEnum, 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, sortByLastMessage, sortByLastUpdated, sortByLocalSortingDate, sortByName, sortBySegmentNumber, subscribeTopic, toPage, toPageRaw, toToken, upsertInCache, validateUntilAt, wipeCache };