posterly-mcp-server 0.48.5 → 0.49.0

package/dist/tools/list-posts.js

@@ -1,10 +1,20 @@
 import { z } from 'zod';
-import { dashboardUrlForPostList, formatLocalDateTime, truncateText } from '../lib/format.js';
+import { dashboardUrlForPostList, formatPostCounts, formatPostListPage } from '../lib/format.js';
+import { validateArgs } from '../lib/tool-runtime.js';
 import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+export const LIST_POSTS_DESCRIPTION = 'Posts in your workspaces, teammates\' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to. ' +
+    'view=list (default): posts filtered by status (scheduled, published, failed, draft), platform, account_id, workspace_id, brand_id, approval_status, approval_waiting_on, and a scheduled date range: scheduled_from (inclusive) and scheduled_to (a plain date includes that whole day), read in timezone (IANA, default UTC; also the zone times are shown in). Returns limit posts (default 20, max 200) starting at offset; with a date range the order defaults to oldest first (order=asc|desc). ' +
+    'The output always says whether every matching post was shown. If it says more are available, call again with the offset it gives and keep paging until all are shown before drawing any conclusion about totals, gaps, or how busy a client is. ' +
+    'view=counts (scheduled_from and scheduled_to required, up to 366 days): exact totals per day, status, account, and brand for the same filters (limit, offset, and order are ignored); use it for "how many" or "is this month full" questions. ' +
+    'approval_waiting_on=client is the same queue as approval_status=pending_client. Each post includes approval.pending_client_approval.';
 export const listPostsTool = {
     name: 'list_posts',
-    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft), platform, account_id, workspace_id, approval_status, approval_waiting_on, or brand_id. approval_waiting_on=client is the same queue as approval_status=pending_client. Each post includes approval.pending_client_approval. Returns posts in your workspaces, teammates\' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to.',
+    description: LIST_POSTS_DESCRIPTION,
     inputSchema: z.object({
+        view: z
+            .enum(['list', 'counts'])
+            .optional()
+            .describe('list (default): the posts themselves, one page at a time. counts: exact totals per day, status, account, and brand (needs scheduled_from and scheduled_to).'),
         status: z
             .string()
             .optional()
@@ -17,12 +27,34 @@ export const listPostsTool = {
             .string()
             .optional()
             .describe('Filter to a specific social account ID (from list_accounts).'),
+        scheduled_from: z
+            .string()
+            .optional()
+            .describe('Start of the scheduled range, inclusive: a date (2026-10-01) or an ISO date-time. Plain dates and times without an offset are read in timezone.'),
+        scheduled_to: z
+            .string()
+            .optional()
+            .describe('End of the scheduled range: a plain date (2026-10-31) includes that whole day; an ISO date-time is exclusive.'),
+        timezone: z
+            .string()
+            .optional()
+            .describe('IANA time zone such as Europe/London for reading plain dates and showing times. Default UTC.'),
+        order: z
+            .enum(['asc', 'desc'])
+            .optional()
+            .describe('asc (oldest first) or desc (newest first). Default asc with a date range, otherwise desc. Ignored by view=counts.'),
         limit: z
             .number()
             .min(1)
-            .max(100)
+            .max(200)
             .optional()
-            .describe('Number of posts to return (default 20, max 100)'),
+            .describe('Posts per page (default 20, max 200). Ignored by view=counts.'),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('How many matching posts to skip. Use the offset the previous page gives to get the next page. Ignored by view=counts.'),
         workspace_id: z
             .string()
             .optional()
@@ -40,36 +72,34 @@ export const listPostsTool = {
             .optional()
             .describe('Filter to posts assigned to a specific brand/client (the id from list_brands).'),
     }),
-    async execute(client, input) {
-        const { posts, total } = await client.listPosts({
-            ...input,
-            limit: input.limit || 20,
-        });
-        if (posts.length === 0) {
-            return 'No posts found matching your criteria.\n\nNext step for the AI agent: tell the user their posterly queue is clear for that filter, then ask what they want to schedule next.';
+    async execute(client, input, ctx) {
+        const { mode, args } = validateArgs(ctx, 'list_posts', input);
+        const filters = postFilters(args);
+        const timeZone = filters.timezone || 'UTC';
+        if (mode === 'counts') {
+            return formatPostCounts(await client.countPosts(filters));
         }
-        const lines = posts.map((p) => {
-            const date = formatLocalDateTime(p.scheduled_at);
-            const caption = truncateText(p.content, 60);
-            const approvalBits = [];
-            if (p.approval && p.approval.status !== 'none') {
-                approvalBits.push(`approval: ${p.approval.status}`);
-                if (p.approval.waiting_on)
-                    approvalBits.push(`waiting on: ${p.approval.waiting_on}`);
-            }
-            if (p.brand_id)
-                approvalBits.push(`brand: ${p.brand_id}`);
-            if (p.content_plan_id)
-                approvalBits.push(`plan: ${p.content_plan_id}`);
-            const approvalSuffix = approvalBits.length > 0 ? ` [${approvalBits.join(', ')}]` : '';
-            return `• [${p.status}] #${p.id}: ${caption} (${date})${approvalSuffix}`;
+        const hasRange = Boolean(filters.scheduled_from || filters.scheduled_to);
+        const page = await client.listPosts({
+            ...filters,
+            limit: args.limit || 20,
+            offset: args.offset,
+            order: args.order ?? (hasRange ? 'asc' : undefined),
         });
-        return [
-            `Posts (${posts.length} of ${total}):`,
-            ...lines,
-            '',
-            `View in posterly: ${dashboardUrlForPostList(posts)}`,
-            'Next step for the AI agent: summarize the queue in plain language and use the dashboard link above if the user wants to inspect it in posterly.',
-        ].join('\n');
+        return formatPostListPage(page, { timeZone, dashboardUrl: dashboardUrlForPostList(page.posts || []) });
     },
 };
+function postFilters(input) {
+    return {
+        status: input.status,
+        platform: input.platform,
+        account_id: input.account_id,
+        workspace_id: input.workspace_id,
+        approval_status: input.approval_status,
+        approval_waiting_on: input.approval_waiting_on,
+        brand_id: input.brand_id,
+        scheduled_from: input.scheduled_from,
+        scheduled_to: input.scheduled_to,
+        timezone: input.timezone,
+    };
+}

package/dist/tools/manage-comment.d.ts

@@ -28,9 +28,9 @@ export declare const manageCommentTool: {
     }, "strip", z.ZodTypeAny, {
         action: "update" | "delete" | "reply";
         comment_id: string;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
         type?: "public" | "private" | undefined;
         content?: string | undefined;
         is_hidden?: boolean | undefined;
@@ -38,9 +38,9 @@ export declare const manageCommentTool: {
     }, {
         action: "update" | "delete" | "reply";
         comment_id: string;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
         type?: "public" | "private" | undefined;
         content?: string | undefined;
         is_hidden?: boolean | undefined;

package/dist/tools/manage-conversation.d.ts

@@ -25,19 +25,19 @@ export declare const manageConversationTool: {
         preview_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         action: "send" | "sync";
+        account_id?: number | undefined;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
-        account_id?: number | undefined;
         content?: string | undefined;
         conversation_id?: string | undefined;
         sync_type?: "all" | "dm" | "comments" | undefined;
     }, {
         action: "send" | "sync";
+        account_id?: number | undefined;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
-        account_id?: number | undefined;
         content?: string | undefined;
         conversation_id?: string | undefined;
         sync_type?: "all" | "dm" | "comments" | undefined;

package/dist/tools/manage-google-business-media.d.ts

@@ -30,10 +30,10 @@ export declare const manageGoogleBusinessMediaTool: {
         preview_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         action: "delete" | "add";
+        account_id?: number | undefined;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
-        account_id?: number | undefined;
         location_id?: string | undefined;
         category?: "COVER" | "PROFILE" | "LOGO" | "EXTERIOR" | "INTERIOR" | "PRODUCT" | "AT_WORK" | "FOOD_AND_DRINK" | "MENU" | "COMMON_AREA" | "ROOMS" | "TEAMS" | "ADDITIONAL" | undefined;
         source_url?: string | undefined;
@@ -41,10 +41,10 @@ export declare const manageGoogleBusinessMediaTool: {
         media_name?: string | undefined;
     }, {
         action: "delete" | "add";
+        account_id?: number | undefined;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
-        account_id?: number | undefined;
         location_id?: string | undefined;
         category?: "COVER" | "PROFILE" | "LOGO" | "EXTERIOR" | "INTERIOR" | "PRODUCT" | "AT_WORK" | "FOOD_AND_DRINK" | "MENU" | "COMMON_AREA" | "ROOMS" | "TEAMS" | "ADDITIONAL" | undefined;
         source_url?: string | undefined;
@@ -65,16 +65,16 @@ export declare const manageGoogleBusinessMediaTool: {
             confirm: true;
             category: "COVER" | "PROFILE" | "LOGO" | "EXTERIOR" | "INTERIOR" | "PRODUCT" | "AT_WORK" | "FOOD_AND_DRINK" | "MENU" | "COMMON_AREA" | "ROOMS" | "TEAMS" | "ADDITIONAL";
             source_url: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
             media_format?: "PHOTO" | "VIDEO" | undefined;
         }, {
             confirm: true;
             category: "COVER" | "PROFILE" | "LOGO" | "EXTERIOR" | "INTERIOR" | "PRODUCT" | "AT_WORK" | "FOOD_AND_DRINK" | "MENU" | "COMMON_AREA" | "ROOMS" | "TEAMS" | "ADDITIONAL";
             source_url: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
             media_format?: "PHOTO" | "VIDEO" | undefined;
         }>;
@@ -87,14 +87,14 @@ export declare const manageGoogleBusinessMediaTool: {
         }, "strip", z.ZodTypeAny, {
             confirm: true;
             media_name: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
         }, {
             confirm: true;
             media_name: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
         }>;
     };

package/dist/tools/manage-google-business-review.d.ts

@@ -37,10 +37,10 @@ export declare const manageGoogleBusinessReviewTool: {
         preview_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         action: "suggest_reply" | "reply" | "delete_reply";
+        account_id?: number | undefined;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
-        account_id?: number | undefined;
         count?: number | undefined;
         location_id?: string | undefined;
         comment?: string | undefined;
@@ -52,10 +52,10 @@ export declare const manageGoogleBusinessReviewTool: {
         business_name?: string | undefined;
     }, {
         action: "suggest_reply" | "reply" | "delete_reply";
+        account_id?: number | undefined;
+        workspace_id?: string | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | undefined;
-        account_id?: number | undefined;
         count?: number | undefined;
         location_id?: string | undefined;
         comment?: string | undefined;
@@ -80,8 +80,8 @@ export declare const manageGoogleBusinessReviewTool: {
             location_id: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             star_rating: number;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             count?: number | undefined;
             location_id?: string | undefined;
             tone?: "professional" | "friendly" | "apologetic" | undefined;
@@ -90,8 +90,8 @@ export declare const manageGoogleBusinessReviewTool: {
             business_name?: string | undefined;
         }, {
             star_rating: number;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             count?: number | undefined;
             location_id?: string | undefined;
             tone?: "professional" | "friendly" | "apologetic" | undefined;
@@ -110,15 +110,15 @@ export declare const manageGoogleBusinessReviewTool: {
             confirm: true;
             comment: string;
             review_name: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
         }, {
             confirm: true;
             comment: string;
             review_name: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
         }>;
         delete_google_business_review_reply: z.ZodObject<{
@@ -130,14 +130,14 @@ export declare const manageGoogleBusinessReviewTool: {
         }, "strip", z.ZodTypeAny, {
             confirm: true;
             review_name: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
         }, {
             confirm: true;
             review_name: string;
-            workspace_id?: string | undefined;
             account_id?: number | undefined;
+            workspace_id?: string | undefined;
             location_id?: string | undefined;
         }>;
     };

package/dist/tools/manage-publishing-pause.d.ts

@@ -19,15 +19,15 @@ export declare const managePublishingPauseTool: {
         confirm: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         action: "pause" | "resume" | "publish_missed";
-        confirm?: boolean | undefined;
         workspace_id?: string | undefined;
         brand_id?: string | undefined;
+        confirm?: boolean | undefined;
         post_ids?: number[] | undefined;
     }, {
         action: "pause" | "resume" | "publish_missed";
-        confirm?: boolean | undefined;
         workspace_id?: string | undefined;
         brand_id?: string | undefined;
+        confirm?: boolean | undefined;
         post_ids?: number[] | undefined;
     }>;
     execute(client: PosterlyClient, input: ManagePublishingPauseInput, ctx: ToolContext): Promise<string>;

package/dist/tools/manage-webhook.d.ts

@@ -28,20 +28,20 @@ export declare const manageWebhookTool: {
     }, "strip", z.ZodTypeAny, {
         action: "update" | "delete" | "test";
         webhook_id: string;
+        workspace_id?: string | null | undefined;
         description?: string | null | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | null | undefined;
         url?: string | undefined;
         is_active?: boolean | undefined;
         events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
     }, {
         action: "update" | "delete" | "test";
         webhook_id: string;
+        workspace_id?: string | null | undefined;
         description?: string | null | undefined;
         confirm?: boolean | undefined;
         preview_id?: string | undefined;
-        workspace_id?: string | null | undefined;
         url?: string | undefined;
         is_active?: boolean | undefined;
         events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
@@ -59,16 +59,16 @@ export declare const manageWebhookTool: {
         }, "strip", z.ZodTypeAny, {
             confirm: true;
             webhook_id: string;
-            description?: string | null | undefined;
             workspace_id?: string | null | undefined;
+            description?: string | null | undefined;
             url?: string | undefined;
             is_active?: boolean | undefined;
             events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
         }, {
             confirm: true;
             webhook_id: string;
-            description?: string | null | undefined;
             workspace_id?: string | null | undefined;
+            description?: string | null | undefined;
             url?: string | undefined;
             is_active?: boolean | undefined;
             events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;

package/dist/tools/validate-post.d.ts

@@ -653,9 +653,9 @@ export declare const validatePostInputSchema: import("zod").ZodObject<{
     workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
 }, "strip", import("zod").ZodTypeAny, {
     platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-    username?: string | undefined;
-    workspace_id?: string | undefined;
     account_id?: string | undefined;
+    workspace_id?: string | undefined;
+    username?: string | undefined;
     caption?: string | undefined;
     scheduled_at?: string | undefined;
     media_url?: string | undefined;
@@ -854,9 +854,9 @@ export declare const validatePostInputSchema: import("zod").ZodObject<{
     }, import("zod").ZodTypeAny, "passthrough"> | undefined;
 }, {
     platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-    username?: string | undefined;
-    workspace_id?: string | undefined;
     account_id?: string | undefined;
+    workspace_id?: string | undefined;
+    username?: string | undefined;
     caption?: string | undefined;
     scheduled_at?: string | undefined;
     media_url?: string | undefined;
@@ -1711,9 +1711,9 @@ export declare const validatePostTool: {
         workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
     }, "strip", import("zod").ZodTypeAny, {
         platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-        username?: string | undefined;
-        workspace_id?: string | undefined;
         account_id?: string | undefined;
+        workspace_id?: string | undefined;
+        username?: string | undefined;
         caption?: string | undefined;
         scheduled_at?: string | undefined;
         media_url?: string | undefined;
@@ -1912,9 +1912,9 @@ export declare const validatePostTool: {
         }, import("zod").ZodTypeAny, "passthrough"> | undefined;
     }, {
         platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
-        username?: string | undefined;
-        workspace_id?: string | undefined;
         account_id?: string | undefined;
+        workspace_id?: string | undefined;
+        username?: string | undefined;
         caption?: string | undefined;
         scheduled_at?: string | undefined;
         media_url?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.48.5",
+  "version": "0.49.0",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.48.5",
+  "version": "0.49.0",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.48.5",
+      "version": "0.49.0",
       "transport": {
         "type": "stdio"
       },

package/src/lib/api-client.ts

@@ -176,6 +176,11 @@ export interface PostSuggestion {
 
 export interface PostSuggestionsResponse {
   suggestions: PostSuggestion[];
+  total?: number;
+  limit?: number;
+  offset?: number;
+  has_more?: boolean;
+  next_offset?: number | null;
 }
 
 export interface DismissSuggestionResponse {
@@ -216,6 +221,63 @@ export interface Post {
   approval?: ApiPostApproval;
 }
 
+/** Filters shared by GET /posts and GET /posts/counts. */
+export interface ListPostsParams {
+  status?: string;
+  platform?: string;
+  account_id?: string;
+  workspace_id?: string;
+  approval_status?: string;
+  approval_waiting_on?: string;
+  brand_id?: string;
+  scheduled_from?: string;
+  scheduled_to?: string;
+  timezone?: string;
+}
+
+export interface PostsRangeEcho {
+  from: string | null;
+  to: string | null;
+  timezone: string;
+}
+
+export interface ListPostsResponse {
+  posts: Post[];
+  total: number;
+  limit?: number;
+  offset?: number;
+  has_more?: boolean;
+  next_offset?: number | null;
+  order?: 'asc' | 'desc';
+  range?: PostsRangeEcho | null;
+}
+
+export interface PostCountsResponse {
+  total: number;
+  counted: number;
+  truncated: boolean;
+  range: PostsRangeEcho | null;
+  by_day: Array<{ date: string; count: number }>;
+  by_status: Array<{ status: string; count: number }>;
+  by_account: Array<{ account_id: string | null; platform: string | null; username: string | null; count: number }>;
+  by_brand: Array<{ brand_id: string | null; name: string | null; count: number }>;
+}
+
+function postFilterParams(params?: ListPostsParams): URLSearchParams {
+  const searchParams = new URLSearchParams();
+  if (params?.status) searchParams.set('status', params.status);
+  if (params?.platform) searchParams.set('platform', params.platform);
+  if (params?.account_id) searchParams.set('account_id', params.account_id);
+  if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+  if (params?.approval_status) searchParams.set('approval_status', params.approval_status);
+  if (params?.approval_waiting_on) searchParams.set('approval_waiting_on', params.approval_waiting_on);
+  if (params?.brand_id) searchParams.set('brand_id', params.brand_id);
+  if (params?.scheduled_from) searchParams.set('scheduled_from', params.scheduled_from);
+  if (params?.scheduled_to) searchParams.set('scheduled_to', params.scheduled_to);
+  if (params?.timezone) searchParams.set('timezone', params.timezone);
+  return searchParams;
+}
+
 export interface InstagramPostSettings {
   __type?: 'instagram' | 'instagram-standalone';
   post_type?: 'post' | 'feed' | 'story' | 'reel' | 'carousel';
@@ -930,8 +992,12 @@ export interface ActivityItem {
 
 export interface ActivityResponse {
   items: ActivityItem[];
+  /** Items on this page (kept for older clients); use has_more to tell whether more exist. */
   total: number;
   limit: number;
+  offset?: number;
+  has_more?: boolean;
+  next_offset?: number | null;
 }
 
 export interface UpdateEntry {
@@ -950,6 +1016,11 @@ export interface UpdateEntry {
 
 export interface UpdatesResponse {
   updates: UpdateEntry[];
+  total?: number;
+  limit?: number;
+  offset?: number;
+  has_more?: boolean;
+  next_offset?: number | null;
 }
 
 export interface ApiWebhook {
@@ -1647,11 +1718,13 @@ export class PosterlyClient {
     account_id?: string | number;
     status?: 'pending' | 'scheduled' | 'dismissed';
     limit?: number;
+    offset?: number;
   }): Promise<PostSuggestionsResponse> {
     const searchParams = new URLSearchParams();
     if (params?.account_id) searchParams.set('account_id', String(params.account_id));
     if (params?.status) searchParams.set('status', params.status);
     if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset) searchParams.set('offset', String(params.offset));
     const qs = searchParams.toString();
     return this.request('GET', `/suggestions${qs ? `?${qs}` : ''}`);
   }
@@ -1660,32 +1733,26 @@ export class PosterlyClient {
     return this.request('POST', `/suggestions/${encodeURIComponent(id)}/dismiss`, {});
   }
 
-  async listPosts(params?: {
-    status?: string;
-    platform?: string;
-    account_id?: string;
+  async listPosts(params?: ListPostsParams & {
     limit?: number;
     offset?: number;
-    workspace_id?: string;
-    approval_status?: string;
-    approval_waiting_on?: string;
-    brand_id?: string;
-  }): Promise<{ posts: Post[]; total: number }> {
-    const searchParams = new URLSearchParams();
-    if (params?.status) searchParams.set('status', params.status);
-    if (params?.platform) searchParams.set('platform', params.platform);
-    if (params?.account_id) searchParams.set('account_id', params.account_id);
+    order?: 'asc' | 'desc';
+  }): Promise<ListPostsResponse> {
+    const searchParams = postFilterParams(params);
     if (params?.limit) searchParams.set('limit', String(params.limit));
     if (params?.offset) searchParams.set('offset', String(params.offset));
-    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
-    if (params?.approval_status) searchParams.set('approval_status', params.approval_status);
-    if (params?.approval_waiting_on) searchParams.set('approval_waiting_on', params.approval_waiting_on);
-    if (params?.brand_id) searchParams.set('brand_id', params.brand_id);
+    if (params?.order) searchParams.set('order', params.order);
 
     const qs = searchParams.toString();
     return this.request('GET', `/posts${qs ? `?${qs}` : ''}`);
   }
 
+  /** GET /posts/counts: exact totals per day, status, account, and brand for a scheduled range. */
+  async countPosts(params: ListPostsParams): Promise<PostCountsResponse> {
+    const qs = postFilterParams(params).toString();
+    return this.request('GET', `/posts/counts${qs ? `?${qs}` : ''}`);
+  }
+
   async createPost(data: CreatePostPayload): Promise<CreatePostResponse> {
     return this.request('POST', '/posts', data);
   }
@@ -2053,6 +2120,7 @@ export class PosterlyClient {
     since?: string;
     type?: 'all' | 'activity' | 'publish';
     limit?: number;
+    offset?: number;
   }): Promise<ActivityResponse> {
     const searchParams = new URLSearchParams();
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
@@ -2060,17 +2128,20 @@ export class PosterlyClient {
     if (params?.since) searchParams.set('since', params.since);
     if (params?.type) searchParams.set('type', params.type);
     if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset) searchParams.set('offset', String(params.offset));
     const qs = searchParams.toString();
     return this.request('GET', `/activity${qs ? `?${qs}` : ''}`);
   }
 
   async getUpdates(params?: {
     limit?: number;
+    offset?: number;
     since?: string;
     include_content?: boolean;
   }): Promise<UpdatesResponse> {
     const searchParams = new URLSearchParams();
     if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset) searchParams.set('offset', String(params.offset));
     if (params?.since) searchParams.set('since', params.since);
     if (params?.include_content) searchParams.set('include_content', 'true');
     const qs = searchParams.toString();
@@ -2193,6 +2264,7 @@ export class PosterlyClient {
 
   async listMedia(params?: {
     limit?: number;
+    offset?: number;
     dropSessionId?: string;
   }): Promise<{
     media: Array<{
@@ -2206,9 +2278,14 @@ export class PosterlyClient {
       drop_session_id: string | null;
     }>;
     total: number;
+    limit?: number;
+    offset?: number;
+    has_more?: boolean;
+    next_offset?: number | null;
   }> {
     const searchParams = new URLSearchParams();
     if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset) searchParams.set('offset', String(params.offset));
     if (params?.dropSessionId) searchParams.set('drop_session_id', params.dropSessionId);
     const qs = searchParams.toString();
     return this.request('GET', `/media${qs ? `?${qs}` : ''}`);