@terminal3/t3n-sdk 4.40.0 → 4.42.0

package/dist/index.d.ts

@@ -2322,7 +2322,20 @@ interface ActivityReport {
      */
     next_seq: number | null;
 }
-/** Params for one activity-report page. All optional; `{}` is valid. */
+/**
+ * Params for one activity-report page. All optional; `{}` is valid.
+ *
+ * The row filters (`caller_type`, `outcome`, `did`, `contract`, `function`)
+ * are AND-ed and applied node-side before the page is filled, so `limit` keeps
+ * counting *matching* rows and the cursor keeps its meaning — page a filtered
+ * report exactly as an unfiltered one, resending the same filters with every
+ * `before_seq`. They narrow what comes back, not what the node scans, so short
+ * and empty pages with a live `next_seq` are the normal case under a selective
+ * filter.
+ *
+ * A field the node does not recognise is rejected (400) rather than ignored,
+ * so a filter never silently widens a query back to the whole organisation.
+ */
 interface GetActivityLogOptions {
     /** Window start, Unix ms, inclusive. Defaults to 0 (no lower bound). */
     from_ms?: number;
@@ -2341,6 +2354,31 @@ interface GetActivityLogOptions {
      * the node's own scan cap can trip first. See {@link ActivityReport.next_seq}.
      */
     limit?: number;
+    /** Keep only calls made by an agent, or only those made by a human. */
+    caller_type?: ActivityCallerType;
+    /** Keep only calls that ended in this outcome. */
+    outcome?: ActivityOutcome;
+    /**
+     * Keep only calls this DID took part in — as the {@link ActivityEntry.actor}
+     * that ran them, or as the {@link ActivityEntry.on_behalf_of} owner they ran
+     * for. Both sides match: "what did this agent do" and "what was done in my
+     * name" are the same question from the two ends of one delegation.
+     *
+     * One whole `did:t3n:<40-hex>`. A partial DID is rejected rather than widened
+     * into a prefix search, so a search box should send this only once it holds a
+     * complete DID.
+     */
+    did?: string;
+    /**
+     * Keep only calls whose {@link ActivityEntry.contract} contains this
+     * substring, compared case-insensitively. Must not be empty.
+     */
+    contract?: string;
+    /**
+     * Keep only calls whose {@link ActivityEntry.function} contains this
+     * substring, compared case-insensitively. Must not be empty.
+     */
+    function?: string;
 }
 
 /**
@@ -2816,6 +2854,22 @@ declare class T3nClient {
      *   cursor = page.next_seq ?? undefined;
      * } while (cursor !== undefined);
      * ```
+     *
+     * The optional row filters — `caller_type`, `outcome`, `did`, `contract`,
+     * `function` — are AND-ed node-side and applied before the page is filled, so
+     * they compose freely with each other and with the cursor. Resend the same
+     * filters with every page; changing them mid-walk changes what the cursor
+     * means. Because a filter narrows what comes back rather than what the node
+     * scans, short and empty pages are the normal case — page until `next_seq` is
+     * `null`.
+     *
+     * ```ts
+     * // Everything one agent did, or had done in its name, that was refused.
+     * const denied = await client.getActivityLog({
+     *   did: "did:t3n:8a2fbc8a2fbc8a2fbc8a2fbc8a2fbc8a2fbc8a2f",
+     *   outcome: "denied",
+     * });
+     * ```
      */
     getActivityLog(opts?: GetActivityLogOptions): Promise<ActivityReport>;
     /**