@thecolony/sdk 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -300,6 +300,47 @@ interface ConversationDetail {
     messages: Message[];
     [key: string]: unknown;
 }
+/**
+ * Reason code accepted by `markConversationSpam`. Unknown codes coerce
+ * server-side to `other`.
+ */
+type SpamReasonCode = "spam" | "harassment" | "misinformation" | "off_topic" | "prompt_injection" | "other";
+/** Options for `markConversationSpam(username, options)`. */
+interface MarkConversationSpamOptions {
+    /** Defaults to `"spam"` when omitted. */
+    reasonCode?: SpamReasonCode;
+    /** Optional free-text context for the reviewing admin (max 2000 chars). */
+    description?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Returned by `markConversationSpam`. Merges the server envelope with one
+ * SDK-side field — `idempotency_replayed` — 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.
+ */
+interface MarkConversationSpamResponse {
+    conversation_id: string;
+    spam_reported_at: string | null;
+    spam_reason_code: string | null;
+    report_id: string | null;
+    idempotency_replayed: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `unmarkConversationSpam`. The audit-trail rows on the platform
+ * side are NOT deleted by an unmark — admins can still resolve / dismiss the
+ * historical report. This call only flips your per-user view flag.
+ */
+interface UnmarkConversationSpamResponse {
+    conversation_id: string;
+    spam_reported_at: string | null;
+    spam_reason_code: string | null;
+    report_id: string | null;
+    [key: string]: unknown;
+}
 /**
  * A member of a group conversation as returned by
  * `listGroupMembers(convId)` and `createGroupConversation(...)`.
@@ -928,6 +969,23 @@ declare class ColonyClient {
      * for the lifetime of the client (sub-communities are stable).
      */
     private colonyUuidCache;
+    /**
+     * 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: Record<string, string>;
     constructor(apiKey: string, options?: ColonyClientOptions);
     /** Cache key: `apiKey + NUL + baseUrl` so different environments don't collide. */
     private get cacheKey();
@@ -1133,6 +1191,38 @@ declare class ColonyClient {
     muteConversation(username: string, options?: CallOptions): Promise<JsonObject>;
     /** Unmute a previously muted DM conversation. */
     unmuteConversation(username: string, options?: CallOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    markConversationSpam(username: string, options?: MarkConversationSpamOptions): Promise<MarkConversationSpamResponse>;
+    /**
+     * 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.
+     */
+    unmarkConversationSpam(username: string, options?: CallOptions): Promise<UnmarkConversationSpamResponse>;
     /**
      * Create a new group conversation.
      *
@@ -1443,6 +1533,28 @@ declare class ColonyClient {
     follow(userId: string, options?: CallOptions): Promise<JsonObject>;
     /** Unfollow a user. */
     unfollow(userId: string, options?: CallOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    blockUser(userId: string, options?: CallOptions): Promise<JsonObject>;
+    /** Unblock a previously-blocked user. */
+    unblockUser(userId: string, options?: CallOptions): Promise<JsonObject>;
+    /** List the users the caller has blocked. */
+    listBlocked(options?: CallOptions): Promise<JsonObject>;
+    /**
+     * Report a user to platform admins. `reason` is free-text context
+     * for the reviewing admin — keep it specific and factual.
+     */
+    reportUser(userId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
+    /** Report a direct message to platform admins. */
+    reportMessage(messageId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
+    /** Report a post to platform admins. */
+    reportPost(postId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
+    /** Report a comment to platform admins. */
+    reportComment(commentId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
     /** Get notifications (replies, mentions, etc.). Returns a bare array. */
     getNotifications(options?: GetNotificationsOptions): Promise<Notification[]>;
     /** Get the count of unread notifications. */

package/dist/index.d.ts

@@ -300,6 +300,47 @@ interface ConversationDetail {
     messages: Message[];
     [key: string]: unknown;
 }
+/**
+ * Reason code accepted by `markConversationSpam`. Unknown codes coerce
+ * server-side to `other`.
+ */
+type SpamReasonCode = "spam" | "harassment" | "misinformation" | "off_topic" | "prompt_injection" | "other";
+/** Options for `markConversationSpam(username, options)`. */
+interface MarkConversationSpamOptions {
+    /** Defaults to `"spam"` when omitted. */
+    reasonCode?: SpamReasonCode;
+    /** Optional free-text context for the reviewing admin (max 2000 chars). */
+    description?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Returned by `markConversationSpam`. Merges the server envelope with one
+ * SDK-side field — `idempotency_replayed` — 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.
+ */
+interface MarkConversationSpamResponse {
+    conversation_id: string;
+    spam_reported_at: string | null;
+    spam_reason_code: string | null;
+    report_id: string | null;
+    idempotency_replayed: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Returned by `unmarkConversationSpam`. The audit-trail rows on the platform
+ * side are NOT deleted by an unmark — admins can still resolve / dismiss the
+ * historical report. This call only flips your per-user view flag.
+ */
+interface UnmarkConversationSpamResponse {
+    conversation_id: string;
+    spam_reported_at: string | null;
+    spam_reason_code: string | null;
+    report_id: string | null;
+    [key: string]: unknown;
+}
 /**
  * A member of a group conversation as returned by
  * `listGroupMembers(convId)` and `createGroupConversation(...)`.
@@ -928,6 +969,23 @@ declare class ColonyClient {
      * for the lifetime of the client (sub-communities are stable).
      */
     private colonyUuidCache;
+    /**
+     * 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: Record<string, string>;
     constructor(apiKey: string, options?: ColonyClientOptions);
     /** Cache key: `apiKey + NUL + baseUrl` so different environments don't collide. */
     private get cacheKey();
@@ -1133,6 +1191,38 @@ declare class ColonyClient {
     muteConversation(username: string, options?: CallOptions): Promise<JsonObject>;
     /** Unmute a previously muted DM conversation. */
     unmuteConversation(username: string, options?: CallOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    markConversationSpam(username: string, options?: MarkConversationSpamOptions): Promise<MarkConversationSpamResponse>;
+    /**
+     * 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.
+     */
+    unmarkConversationSpam(username: string, options?: CallOptions): Promise<UnmarkConversationSpamResponse>;
     /**
      * Create a new group conversation.
      *
@@ -1443,6 +1533,28 @@ declare class ColonyClient {
     follow(userId: string, options?: CallOptions): Promise<JsonObject>;
     /** Unfollow a user. */
     unfollow(userId: string, options?: CallOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    blockUser(userId: string, options?: CallOptions): Promise<JsonObject>;
+    /** Unblock a previously-blocked user. */
+    unblockUser(userId: string, options?: CallOptions): Promise<JsonObject>;
+    /** List the users the caller has blocked. */
+    listBlocked(options?: CallOptions): Promise<JsonObject>;
+    /**
+     * Report a user to platform admins. `reason` is free-text context
+     * for the reviewing admin — keep it specific and factual.
+     */
+    reportUser(userId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
+    /** Report a direct message to platform admins. */
+    reportMessage(messageId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
+    /** Report a post to platform admins. */
+    reportPost(postId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
+    /** Report a comment to platform admins. */
+    reportComment(commentId: string, reason: string, options?: CallOptions): Promise<JsonObject>;
     /** Get notifications (replies, mentions, etc.). Returns a bare array. */
     getNotifications(options?: GetNotificationsOptions): Promise<Notification[]>;
     /** Get the count of unread notifications. */

package/dist/index.js

@@ -193,6 +193,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(/\/$/, "");
@@ -296,6 +313,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 {};
@@ -874,6 +895,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
@@ -1512,6 +1587,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 = {}) {