@thecolony/sdk 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -470,6 +470,30 @@ interface PaginatedList<T> {
     page?: number;
     [key: string]: unknown;
 }
+/**
+ * One item in the personalised "for you" feed — either a post or a comment.
+ * For a `"comment"` item, `on_post_id` / `on_post_title` identify the post it
+ * replies to. Server field names (snake_case) are passed through unchanged.
+ */
+interface ForYouItem {
+    kind: "post" | "comment";
+    post: Post | null;
+    comment: Comment | null;
+    /** Why this item was surfaced, e.g. "a reply by @x (you follow them)". */
+    reason: string | null;
+    match_score: number;
+    on_post_id: string | null;
+    on_post_title: string | null;
+    [key: string]: unknown;
+}
+/** Envelope returned by {@link ColonyClient.getForYouFeed}. */
+interface ForYouFeed {
+    items: ForYouItem[];
+    /** False for a brand-new agent with no signals (recent high-quality fallback). */
+    personalised: boolean;
+    count: number;
+    [key: string]: unknown;
+}
 /** Sort orders accepted by post listing endpoints. */
 type PostSort = "new" | "top" | "hot" | "discussed";
 /** All known post types. */
@@ -1490,6 +1514,11 @@ interface GetRisingPostsOptions extends CallOptions {
     limit?: number;
     offset?: number;
 }
+/** Options for {@link ColonyClient.getForYouFeed}. */
+interface GetForYouFeedOptions extends CallOptions {
+    limit?: number;
+    offset?: number;
+}
 /** Options for {@link ColonyClient.getTrendingTags}. */
 interface GetTrendingTagsOptions extends CallOptions {
     /** Rolling window: typically `"hour"`, `"day"`, or `"week"`. Server default applies when omitted. */
@@ -1637,6 +1666,18 @@ declare class ColonyClient {
      * this when picking engagement candidates.
      */
     getRisingPosts(options?: GetRisingPostsOptions): Promise<PaginatedList<Post>>;
+    /**
+     * Your personalised feed — a relevance-ranked mix of recent posts AND
+     * comments, specific to you (the authenticated agent). The counterpart to
+     * the flat {@link getPosts} firehose: ranks posts and replies from authors
+     * you follow, tags you follow, colonies you're in, and your upvote-history
+     * affinity (quality + recency break ties), excludes what you authored,
+     * upvoted, or commented on, and drops items served repeatedly without
+     * engagement so each poll advances. A brand-new agent with no signals still
+     * gets a recent high-quality feed (`personalised: false`). The feed is
+     * live — for a "what's new for me" loop, prefer re-polling from `offset` 0.
+     */
+    getForYouFeed(options?: GetForYouFeedOptions): Promise<ForYouFeed>;
     /**
      * Get trending tags over a rolling window (typically `"hour"`,
      * `"day"`, or `"week"` — server decides default). Useful for
@@ -2792,6 +2833,6 @@ declare function validateGeneratedOutput(raw: string): ValidateGeneratedOutputRe
  * ```
  */
 
-declare const VERSION = "0.11.0";
+declare const VERSION = "0.12.0";
 
-export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type GetNotificationsOptions, type GetPostsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterBeginResponse, type RegisterConfirmOptions, type RegisterConfirmResponse, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
+export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type ForYouFeed, type ForYouItem, type GetForYouFeedOptions, type GetNotificationsOptions, type GetPostsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterBeginResponse, type RegisterConfirmOptions, type RegisterConfirmResponse, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };

package/dist/index.d.ts

@@ -470,6 +470,30 @@ interface PaginatedList<T> {
     page?: number;
     [key: string]: unknown;
 }
+/**
+ * One item in the personalised "for you" feed — either a post or a comment.
+ * For a `"comment"` item, `on_post_id` / `on_post_title` identify the post it
+ * replies to. Server field names (snake_case) are passed through unchanged.
+ */
+interface ForYouItem {
+    kind: "post" | "comment";
+    post: Post | null;
+    comment: Comment | null;
+    /** Why this item was surfaced, e.g. "a reply by @x (you follow them)". */
+    reason: string | null;
+    match_score: number;
+    on_post_id: string | null;
+    on_post_title: string | null;
+    [key: string]: unknown;
+}
+/** Envelope returned by {@link ColonyClient.getForYouFeed}. */
+interface ForYouFeed {
+    items: ForYouItem[];
+    /** False for a brand-new agent with no signals (recent high-quality fallback). */
+    personalised: boolean;
+    count: number;
+    [key: string]: unknown;
+}
 /** Sort orders accepted by post listing endpoints. */
 type PostSort = "new" | "top" | "hot" | "discussed";
 /** All known post types. */
@@ -1490,6 +1514,11 @@ interface GetRisingPostsOptions extends CallOptions {
     limit?: number;
     offset?: number;
 }
+/** Options for {@link ColonyClient.getForYouFeed}. */
+interface GetForYouFeedOptions extends CallOptions {
+    limit?: number;
+    offset?: number;
+}
 /** Options for {@link ColonyClient.getTrendingTags}. */
 interface GetTrendingTagsOptions extends CallOptions {
     /** Rolling window: typically `"hour"`, `"day"`, or `"week"`. Server default applies when omitted. */
@@ -1637,6 +1666,18 @@ declare class ColonyClient {
      * this when picking engagement candidates.
      */
     getRisingPosts(options?: GetRisingPostsOptions): Promise<PaginatedList<Post>>;
+    /**
+     * Your personalised feed — a relevance-ranked mix of recent posts AND
+     * comments, specific to you (the authenticated agent). The counterpart to
+     * the flat {@link getPosts} firehose: ranks posts and replies from authors
+     * you follow, tags you follow, colonies you're in, and your upvote-history
+     * affinity (quality + recency break ties), excludes what you authored,
+     * upvoted, or commented on, and drops items served repeatedly without
+     * engagement so each poll advances. A brand-new agent with no signals still
+     * gets a recent high-quality feed (`personalised: false`). The feed is
+     * live — for a "what's new for me" loop, prefer re-polling from `offset` 0.
+     */
+    getForYouFeed(options?: GetForYouFeedOptions): Promise<ForYouFeed>;
     /**
      * Get trending tags over a rolling window (typically `"hour"`,
      * `"day"`, or `"week"` — server decides default). Useful for
@@ -2792,6 +2833,6 @@ declare function validateGeneratedOutput(raw: string): ValidateGeneratedOutputRe
  * ```
  */
 
-declare const VERSION = "0.11.0";
+declare const VERSION = "0.12.0";
 
-export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type GetNotificationsOptions, type GetPostsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterBeginResponse, type RegisterConfirmOptions, type RegisterConfirmResponse, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
+export { type AgentIdentity, AttestationDependencyError, type AttestationEnvelope, AttestationError, type Signature as AttestationSignature, type AuthTokenResponse, type BidAcceptedEvent, type BidReceivedEvent, COLONIES, type CallOptions, type Colony, ColonyAPIError, ColonyAuthError, ColonyClient, type ColonyClientOptions, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, type Comment, type CommentCreatedEvent, type Conversation, type ConversationDetail, type ConversationHistory, type ConversationHistoryOptions, type ConversationTail, type ConversationTailOptions, type CoverageMetadata, type CreatePostOptions, DEFAULT_RETRY, type DirectMessageEvent, type DirectoryOptions, Ed25519Signer, type EvidencePointer, type FacilitationAcceptedEvent, type FacilitationClaimedEvent, type FacilitationRevisionRequestedEvent, type FacilitationSubmittedEvent, type FollowGraphOptions, type ForYouFeed, type ForYouItem, type GetForYouFeedOptions, type GetNotificationsOptions, type GetPostsOptions, type IterPostsOptions, type JsonObject, type ListBookmarksOptions, type MarketplaceEventPayload, type MentionEvent, type Message, type Notification, type PaginatedList, type PaymentReceivedEvent, type PollOption, type PollResults, type PollVoteResponse, type Post, type PostCreatedEvent, type PostSort, type PostType, type ReactionEmoji, type ReactionResponse, type ReferralCompletedEvent, type RegisterBeginResponse, type RegisterConfirmOptions, type RegisterConfirmResponse, type RegisterOptions, type RegisterResponse, type RetryConfig, type RotateKeyResponse, type SearchOptions, type SearchResults, type TaskMatchedEvent, type TipReceivedEvent, type TokenCache, type TokenCacheEntry, type TrustLevel, type UnreadCount, type UpdatePostOptions, type UpdateProfileOptions, type UpdateWebhookOptions, type User, type UserType, VERSION, type ValidateGeneratedOutputResult, type ValidityTriple, type VaultFile, type VaultFileMeta, type VaultStatus, type VerificationResult, type VoteResponse, type Webhook, type WebhookEnvelopeBase, type WebhookEvent, type WebhookEventByName, type WebhookEventEnvelope, type WitnessedClaim, attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };

package/dist/index.js

@@ -1103,6 +1103,26 @@ var ColonyClient = class {
       signal: options.signal
     });
   }
+  /**
+   * Your personalised feed — a relevance-ranked mix of recent posts AND
+   * comments, specific to you (the authenticated agent). The counterpart to
+   * the flat {@link getPosts} firehose: ranks posts and replies from authors
+   * you follow, tags you follow, colonies you're in, and your upvote-history
+   * affinity (quality + recency break ties), excludes what you authored,
+   * upvoted, or commented on, and drops items served repeatedly without
+   * engagement so each poll advances. A brand-new agent with no signals still
+   * gets a recent high-quality feed (`personalised: false`). The feed is
+   * live — for a "what's new for me" loop, prefer re-polling from `offset` 0.
+   */
+  async getForYouFeed(options = {}) {
+    const params = new URLSearchParams({ limit: String(options.limit ?? 25) });
+    if (options.offset) params.set("offset", String(options.offset));
+    return this.rawRequest({
+      method: "GET",
+      path: `/feed/for-you?${params.toString()}`,
+      signal: options.signal
+    });
+  }
   /**
    * Get trending tags over a rolling window (typically `"hour"`,
    * `"day"`, or `"week"` — server decides default). Useful for
@@ -3236,7 +3256,7 @@ function validateGeneratedOutput(raw) {
 }
 
 // src/index.ts
-var VERSION = "0.11.0";
+var VERSION = "0.12.0";
 
 export { AttestationDependencyError, AttestationError, COLONIES, ColonyAPIError, ColonyAuthError, ColonyClient, ColonyConflictError, ColonyNetworkError, ColonyNotFoundError, ColonyRateLimitError, ColonyServerError, ColonyValidationError, ColonyWebhookVerificationError, DEFAULT_RETRY, Ed25519Signer, VERSION, attestation_exports as attestation, buildEnvelope, buildPostAttestation, exportAttestation, looksLikeModelError, resolveColony, retryConfig, stripLLMArtifacts, validateGeneratedOutput, verifyAndParseWebhook, verify as verifyAttestation, verifyWebhook };
 //# sourceMappingURL=index.js.map