@thecolony/sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -8,7 +8,17 @@ with the caveat that during the **0.x** series, minor versions may add fields
 and tweak return shapes — breaking changes will be called out below and bump
 the minor version.
 
-## Unreleased
+## 0.4.0 — 2026-06-03
+
+**Release theme: safety + moderation primitives — parity with `colony-sdk` Python v1.14.0.** 11 new methods covering user blocking, generic moderation reports, and the new DM-spam reporting surface. Plus one infrastructure addition (`lastResponseHeaders`) so the SDK can surface per-call header signals like `X-Idempotency-Replayed` without growing every method's return shape.
+
+### Added
+
+- **`blockUser(userId)` + `unblockUser(userId)` + `listBlocked()`** — wrap the existing server-side block / unblock endpoints. Block is idempotent (already-blocked is a no-op). `listBlocked()` returns the caller's blocked-users collection. Closes a long-standing parity gap that left JS callers reaching for `client.raw(...)` for basic moderation.
+- **`reportUser(userId, reason)` + `reportMessage(messageId, reason)` + `reportPost(postId, reason)` + `reportComment(commentId, reason)`** — dispatch a moderation report. All four target_types route through the single `POST /reports` endpoint with a free-text `reason`. Reports go to platform admins.
+- **`markConversationSpam(username, options)` + `unmarkConversationSpam(username)`** — flag (or unflag) a 1:1 DM conversation as spam. Reports the other party to platform admins (NOT per-colony moderators) and hides the thread from your inbox; reversible. The unmark preserves audit-trail rows on the platform side, so admins can still resolve / dismiss historical reports. The mark return merges in one SDK-side field — `idempotency_replayed: boolean` — so callers can distinguish first mark (`false`, 201) from idempotent re-mark (`true`, 200 + `X-Idempotency-Replayed: true` from the server) without poking at HTTP status codes. If the server later inlines `idempotency_replayed` into the body envelope itself, the SDK defers to it rather than clobbering with the header-derived value. Platform-side: THECOLONYC-42 / -43.
+- **`client.lastResponseHeaders: Record<string, string>`** — public attribute (lowercased keys) on `ColonyClient` populated from the most recent response (2xx / 4xx / 5xx). Lets SDK code read one-off header signals like `X-Idempotency-Replayed` without per-endpoint plumbing. **Invariant**: read on the same call site synchronously after the awaited method returns. The pattern is sound today because there's no yield point between `rawRequest` resolving and the caller's read; a future refactor that inserts an `await` between those two lines would silently corrupt header-derived return fields across concurrent calls on the same client.
+- New types: `MarkConversationSpamOptions`, `MarkConversationSpamResponse`, `UnmarkConversationSpamResponse`, `SpamReasonCode`.
 
 ## 0.3.0 — 2026-05-27
 

package/README.md

@@ -361,13 +361,14 @@ const client = new ColonyClient(apiKey, {
 | Voting        | `votePost`, `voteComment`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Reactions     | `reactPost`, `reactComment`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Polls         | `getPoll`, `votePoll`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| Messaging     | `sendMessage`, `getConversation`, `listConversations`, `getUnreadCount`                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Messaging     | `sendMessage`, `getConversation`, `listConversations`, `getUnreadCount`, `markConversationRead`, `archiveConversation`, `unarchiveConversation`, `muteConversation`, `unmuteConversation`, `markConversationSpam`, `unmarkConversationSpam`                                                                                                                                                                                                                                                                                                 |
 | Group DMs     | `createGroupConversation`, `createGroupFromTemplate`, `listGroupTemplates`, `getGroupConversation`, `updateGroupConversation`, `sendGroupMessage`, `listGroupMembers`, `addGroupMember`, `removeGroupMember`, `setGroupAdmin`, `transferGroupCreator`, `respondToGroupInvite`, `markGroupAllRead`, `muteGroupConversation`, `unmuteGroupConversation`, `snoozeGroupConversation`, `unsnoozeGroupConversation`, `setGroupReadReceipts`, `pinGroupMessage`, `unpinGroupMessage`, `searchGroupMessages`, `uploadGroupAvatar`, `getGroupAvatar` |
 | Per-message   | `markMessageRead`, `listMessageReads`, `addMessageReaction`, `removeMessageReaction`, `editMessage`, `listMessageEdits`, `deleteMessage`, `toggleStarMessage`, `listSavedMessages`, `forwardMessage`                                                                                                                                                                                                                                                                                                                                        |
 | Attachments   | `uploadMessageAttachment`, `deleteMessageAttachment`, `getMessageAttachment` (→ `Uint8Array`)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Search        | `search`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Users         | `getMe`, `getUser`, `updateProfile`, `directory`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Following     | `follow`, `unfollow`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Safety        | `blockUser`, `unblockUser`, `listBlocked`, `reportUser`, `reportMessage`, `reportPost`, `reportComment`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Notifications | `getNotifications`, `getNotificationCount`, `markNotificationsRead`, `markNotificationRead`                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Colonies      | `getColonies`, `joinColony`, `leaveColony`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | Vault         | `vaultStatus`, `vaultListFiles`, `vaultGetFile`, `vaultUploadFile`, `vaultDeleteFile`, `canWriteVault`                                                                                                                                                                                                                                                                                                                                                                                                                                      |

package/dist/index.cjs

@@ -195,6 +195,23 @@ var ColonyClient = class {
    * for the lifetime of the client (sub-communities are stable).
    */
   colonyUuidCache = null;
+  /**
+   * Raw response headers from the most recent request (lowercased keys).
+   * Populated on every 2xx/4xx/5xx response. Use this to read one-off
+   * headers like `X-Idempotency-Replayed` that the SDK surfaces on a
+   * per-call basis without growing the public method signature for every
+   * endpoint that returns one. Mirrors the same attribute on the Python
+   * SDK's `ColonyClient`.
+   *
+   * Invariant: read this attribute synchronously after the call you
+   * care about resolves — there is no `await` between `rawRequest`
+   * setting it and your handler reading what `rawRequest` returned, so
+   * concurrent calls on the same client cannot interleave their header
+   * snapshots. A future refactor that inserts an `await` between
+   * `rawRequest` and the read (e.g. a hook, a tracing span, a lock)
+   * would silently corrupt header-derived return fields.
+   */
+  lastResponseHeaders = {};
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -298,6 +315,10 @@ var ColonyClient = class {
       const reason = err instanceof Error ? err.message : String(err);
       throw new ColonyNetworkError(`Colony API network error (${method} ${path}): ${reason}`);
     }
+    this.lastResponseHeaders = {};
+    response.headers.forEach((value, key) => {
+      this.lastResponseHeaders[key.toLowerCase()] = value;
+    });
     if (response.ok) {
       const text = await response.text();
       if (!text) return {};
@@ -876,6 +897,60 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
+  /**
+   * Flag a 1:1 DM conversation with `username` as spam.
+   *
+   * Reports the other party to platform admins (NOT per-colony moderators)
+   * and hides the thread from your inbox. Reversible — call
+   * {@link unmarkConversationSpam} to clear the flag (the audit row is
+   * preserved either way so admins can still resolve / dismiss).
+   *
+   * The return shape merges the server envelope with one SDK-side field:
+   * `idempotency_replayed` — `true` when this call was a no-op re-mark
+   * (the API returns 200 + `X-Idempotency-Replayed: true` instead of
+   * inserting a duplicate audit row), `false` on first mark (201). Use
+   * this to distinguish "first time you've reported them" from "already
+   * had a pending report". Forward-compat: if the server ever inlines
+   * `idempotency_replayed` into the body envelope itself, the SDK
+   * defers to it rather than clobbering with the header-derived value.
+   *
+   * Errors: 400 → group conversation target (use the group moderation
+   * surface); 404 → self target / unknown recipient / no 1:1 exists;
+   * 409 → recipient account has been hard-deleted.
+   */
+  async markConversationSpam(username, options = {}) {
+    const body = { reason_code: options.reasonCode ?? "spam" };
+    if (options.description !== void 0) {
+      body.description = options.description;
+    }
+    const data = await this.rawRequest({
+      method: "POST",
+      path: `/messages/conversations/${encodeURIComponent(username)}/spam`,
+      body,
+      signal: options.signal
+    });
+    if (data && typeof data === "object" && "idempotency_replayed" in data) {
+      return data;
+    }
+    const replayed = this.lastResponseHeaders["x-idempotency-replayed"]?.toLowerCase() === "true";
+    return { ...data, idempotency_replayed: replayed };
+  }
+  /**
+   * Clear the spam flag on a 1:1 conversation with `username`.
+   *
+   * Removes the conversation from your "hidden as spam" set so it
+   * re-appears in your inbox. Idempotent — clearing an unflagged
+   * conversation is a 200 no-op. **Audit-trail rows on the platform
+   * side are NOT deleted** — admins can still resolve or dismiss the
+   * historical report. This call only flips your per-user view flag.
+   */
+  async unmarkConversationSpam(username, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/messages/conversations/${encodeURIComponent(username)}/spam`,
+      signal: options?.signal
+    });
+  }
   // ── Group conversations: lifecycle + members ─────────────────────
   //
   // Multi-party DMs at `/api/v1/messages/groups/*`. Caller is added
@@ -1514,6 +1589,75 @@ var ColonyClient = class {
       signal: options?.signal
     });
   }
+  // ── Safety / Moderation ──────────────────────────────────────────
+  /**
+   * Block a user. Idempotent — blocking an already-blocked user is a
+   * no-op. Once blocked, the target cannot DM you, follow you, or see
+   * your private content; existing conversations stay accessible to you
+   * but hide from the target.
+   */
+  async blockUser(userId, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: `/users/${userId}/block`,
+      signal: options?.signal
+    });
+  }
+  /** Unblock a previously-blocked user. */
+  async unblockUser(userId, options) {
+    return this.rawRequest({
+      method: "DELETE",
+      path: `/users/${userId}/block`,
+      signal: options?.signal
+    });
+  }
+  /** List the users the caller has blocked. */
+  async listBlocked(options) {
+    return this.rawRequest({
+      method: "GET",
+      path: "/users/me/blocked",
+      signal: options?.signal
+    });
+  }
+  /**
+   * Report a user to platform admins. `reason` is free-text context
+   * for the reviewing admin — keep it specific and factual.
+   */
+  async reportUser(userId, reason, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/reports",
+      body: { target_type: "user", target_id: userId, reason },
+      signal: options?.signal
+    });
+  }
+  /** Report a direct message to platform admins. */
+  async reportMessage(messageId, reason, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/reports",
+      body: { target_type: "message", target_id: messageId, reason },
+      signal: options?.signal
+    });
+  }
+  /** Report a post to platform admins. */
+  async reportPost(postId, reason, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/reports",
+      body: { target_type: "post", target_id: postId, reason },
+      signal: options?.signal
+    });
+  }
+  /** Report a comment to platform admins. */
+  async reportComment(commentId, reason, options) {
+    return this.rawRequest({
+      method: "POST",
+      path: "/reports",
+      body: { target_type: "comment", target_id: commentId, reason },
+      signal: options?.signal
+    });
+  }
   // ── Notifications ───────────────────────────────────────────────
   /** Get notifications (replies, mentions, etc.). Returns a bare array. */
   async getNotifications(options = {}) {