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

package/dist/index.cjs.js

@@ -58,6 +58,18 @@ exports.UserReportTypeEnum = void 0;
     UserReportTypeEnum["AVATAR"] = "avatarFileId";
     UserReportTypeEnum["BEHAVIOR"] = "behavior";
 })(exports.UserReportTypeEnum || (exports.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`.
+ */
+exports.UserProfileFieldEnum = void 0;
+(function (UserProfileFieldEnum) {
+    UserProfileFieldEnum["DISPLAY_NAME"] = "displayName";
+    UserProfileFieldEnum["DESCRIPTION"] = "description";
+    UserProfileFieldEnum["AVATAR"] = "avatarFileId";
+})(exports.UserProfileFieldEnum || (exports.UserProfileFieldEnum = {}));
 
 const FileType = Object.freeze({
     FILE: 'file',
@@ -834,6 +846,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;
 /**
@@ -13451,7 +13475,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 +15274,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,6 +15306,156 @@ 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(exports.UserProfileFieldEnum);
+const BEHAVIOR_REASONS = Object.values(exports.ContentFlagReasonEnum);
+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));
+};
+
+/* 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
 */
@@ -16456,6 +16630,8 @@ var index$r = /*#__PURE__*/Object.freeze({
     getUserByIds: getUserByIds,
     updateUser: updateUser,
     flagUser: flagUser,
+    flagUserProfile: flagUserProfile,
+    flagUserBehavior: flagUserBehavior,
     unflagUser: unflagUser,
     isUserFlaggedByMe: isUserFlaggedByMe,
     getAllBlockedUsers: getAllBlockedUsers,
@@ -20160,23 +20336,85 @@ getDeliveredUsers.locally = (query) => {
     return { data: users, cachedAt, prevPage, nextPage };
 };
 
-/* begin_public_function
-  id: message.flag
-*/
+const CONTENT_FLAG_REASONS = Object.values(exports.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 +20431,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
@@ -27338,23 +27612,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 +27643,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 +30057,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 +30113,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