posterly-mcp-server 0.19.4 → 0.19.6

package/dist/tools/get-account-analytics.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
 export const getAccountAnalyticsTool = {
     name: 'get_account_analytics',
-    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels such as Google Business Profile Views, Search Views, Maps Views, Customer Actions, and Posts.',
+    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
     inputSchema: z.object({
         account_id: z
             .number()
@@ -14,74 +15,138 @@ export const getAccountAnalyticsTool = {
             .string()
             .optional()
             .describe('End date (ISO date). Defaults to today.'),
+        presentation: presentationSchema.describe('Output style: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
     }),
     async execute(client, input) {
         const result = await client.getAccountAnalytics(input);
-        const { account, range, summary, snapshots } = result;
-        const accountLabel = account.platform === 'google_business'
-            ? `${account.username} (Google Business, id ${account.id})`
-            : `@${account.username} (${account.platform}, id ${account.id})`;
-        const lines = [
-            `Analytics for ${accountLabel}`,
-            `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
-            '',
-            'Summary:',
-        ];
-        const nativeRows = getNativeMetricRows(account.platform, summary);
-        if (nativeRows.length > 0) {
-            for (const [label, value] of nativeRows) {
-                pushMetric(lines, label, value);
-            }
-        }
-        else if (account.platform === 'pinterest') {
-            pushGenericSummary(lines, summary);
-            pushMetric(lines, 'Outbound clicks', summary.total_website_clicks);
-        }
-        else if (account.platform === 'youtube') {
-            pushGenericSummary(lines, summary);
-            pushMetric(lines, 'Watch minutes', summary.total_watch_minutes);
-            pushMetric(lines, 'Likes', summary.total_likes);
-        }
-        else {
-            pushGenericSummary(lines, summary);
-        }
-        return lines.join('\n');
+        return formatAccountAnalytics(result, input.presentation || 'compact');
     },
 };
-function getNativeMetricRows(platform, summary) {
-    // API-provided display_metrics is the contract for platform-native dashboards.
-    // Add future non-generic analytics platforms there so MCP output never guesses
-    // from internal storage field names.
-    const apiRows = (summary.display_metrics || [])
-        .filter((metric) => metric?.label)
-        .map((metric) => [metric.label, metric.value]);
-    if (apiRows.length > 0)
-        return apiRows;
+function formatAccountAnalytics(result, presentation) {
+    const { account, range, summary, snapshots } = result;
+    const rows = accountMetricRows(summary, account.platform);
+    const insights = analyticsInsights(summary, account.platform);
+    if (presentation === 'json') {
+        return JSON.stringify({
+            type: 'account_analytics',
+            account,
+            range,
+            snapshot_count: snapshots.length,
+            metrics: rows.map(([label, value]) => ({ label, value })),
+            insights,
+            summary,
+            snapshots,
+        }, null, 2);
+    }
+    if (presentation === 'table') {
+        return [
+            `**📊 Analytics for ${accountLabel(account.username)} (${account.id})**`,
+            `_${account.platform} · ${range.from} → ${range.to}_`,
+            '',
+            '**Account**',
+            markdownTable(['Field', 'Value'], [
+                ['Account ID', String(account.id)],
+                ['Daily snapshots', formatNumber(snapshots.length)],
+            ]),
+            '',
+            '**Metrics**',
+            markdownTable(['Metric', 'Value'], rows),
+            '',
+            '**Quick read**',
+            insights.map((insight) => `- ${insight}`).join('\n'),
+        ].join('\n');
+    }
+    return [
+        `**📊 Analytics for ${accountLabel(account.username)} (${account.id})**`,
+        `_${account.platform} · ${range.from} → ${range.to}_`,
+        '',
+        '**Account**',
+        `- **Account ID:** ${account.id}`,
+        `- **Daily snapshots:** ${formatNumber(snapshots.length)}`,
+        '',
+        '**Key metrics**',
+        rows.map(([label, value]) => `- **${label}:** ${value}`).join('\n'),
+        '',
+        '**Quick read**',
+        insights.map((insight) => `- ${insight}`).join('\n'),
+    ].join('\n');
+}
+function accountMetricRows(summary, platform) {
+    const nativeRows = nativeMetricRows(summary);
+    if (nativeRows.length > 0)
+        return nativeRows;
     if (platform === 'google_business') {
         const metrics = summary.platform_metrics || {};
         return [
-            ['Profile Views', metrics.profile_views ?? summary.total_views],
-            ['Search Views', metrics.search_views ?? summary.total_reach],
-            ['Maps Views', metrics.maps_views ?? summary.total_profile_views],
-            ['Customer Actions', metrics.customer_actions ?? summary.total_accounts_engaged],
-            ['Posts', metrics.posts ?? summary.current_media_count],
+            ['Profile Views', formatNumber(metrics.profile_views ?? summary.total_views)],
+            ['Search Views', formatNumber(metrics.search_views ?? summary.total_reach)],
+            ['Maps Views', formatNumber(metrics.maps_views ?? summary.total_profile_views)],
+            ['Customer Actions', formatNumber(metrics.customer_actions ?? summary.total_accounts_engaged)],
+            ['Posts', formatNumber(metrics.posts ?? summary.current_media_count)],
         ];
     }
-    return [];
+    const rows = genericMetricRows(summary);
+    if (platform === 'pinterest')
+        rows.push(['Outbound clicks', formatNumber(summary.total_website_clicks)]);
+    if (platform === 'youtube') {
+        rows.push(['Watch minutes', formatNumber(summary.total_watch_minutes)]);
+        rows.push(['Likes', formatNumber(summary.total_likes)]);
+    }
+    return rows;
+}
+function nativeMetricRows(summary) {
+    return (summary.display_metrics || [])
+        .filter((metric) => metric?.label)
+        .map((metric) => [metric.label, formatNumber(metric.value)]);
+}
+function genericMetricRows(summary) {
+    return [
+        ['Followers', `${formatNumber(summary.current_followers)} (${formatDelta(summary.followers_change)} in range)`],
+        ['Follows gained / lost', `+${formatNumber(summary.total_follows_gained)} / -${formatNumber(summary.total_follows_lost)}`],
+        ['Total reach', formatNumber(summary.total_reach)],
+        ['Total views', formatNumber(summary.total_views)],
+        ['Profile views', formatNumber(summary.total_profile_views)],
+        ['Accounts engaged', formatNumber(summary.total_accounts_engaged)],
+        ['Engagement rate by reach', formatPercent(summary.engagement_rate)],
+        ['Engagement rate by followers', formatPercent(summary.engagement_rate_by_followers)],
+    ];
+}
+function analyticsInsights(summary, platform) {
+    const insights = [];
+    if (platform === 'google_business' && (summary.display_metrics?.length || 0) > 0) {
+        insights.push('Google Business metrics are shown with dashboard-native labels.');
+    }
+    if ((summary.followers_change || 0) > 0)
+        insights.push(`Audience grew by ${formatDelta(summary.followers_change)} followers in this range.`);
+    if ((summary.followers_change || 0) < 0)
+        insights.push(`Audience dipped by ${formatDelta(summary.followers_change)} followers in this range.`);
+    if (summary.engagement_rate != null && platform !== 'google_business')
+        insights.push(`Engagement by reach is ${formatPercent(summary.engagement_rate)}.`);
+    if (platform === 'youtube' && summary.total_watch_minutes != null)
+        insights.push(`${formatNumber(summary.total_watch_minutes)} total watch minutes were recorded.`);
+    return insights.length ? insights : ['No standout movement detected in the returned period.'];
 }
 function formatDelta(n) {
     return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
 }
-function pushGenericSummary(lines, summary) {
-    lines.push(`• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`, `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`);
-    pushMetric(lines, 'Total reach', summary.total_reach);
-    pushMetric(lines, 'Total views', summary.total_views);
-    pushMetric(lines, 'Profile views', summary.total_profile_views);
-    pushMetric(lines, 'Total accounts engaged', summary.total_accounts_engaged);
-    lines.push(`• Engagement rate (by reach): ${summary.engagement_rate}%`, `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`);
+function formatNumber(value) {
+    return value == null ? 'n/a' : value.toLocaleString();
 }
-function pushMetric(lines, label, value) {
-    if (value != null) {
-        lines.push(`• ${label}: ${value.toLocaleString()}`);
-    }
+function formatPercent(value) {
+    return value == null ? 'n/a' : `${formatNumber(value)}%`;
+}
+function accountLabel(username) {
+    if (!username)
+        return 'account';
+    return username.startsWith('@') || /\s/.test(username) ? username : `@${username}`;
+}
+function markdownTable(headers, rows) {
+    return [
+        `| ${headers.map(escapeCell).join(' | ')} |`,
+        `| ${headers.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+    ].join('\n');
+}
+function escapeCell(value) {
+    return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
 }

package/dist/tools/get-agent-signup-info.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getAgentSignupInfoTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute(client: PosterlyClient): Promise<string>;
+};

package/dist/tools/get-agent-signup-info.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export const getAgentSignupInfoTool = {
+    name: 'get_agent_signup_info',
+    description: 'Explain how to use Posterly MCP for agent-led signup before an API key exists, including the safe human-in-the-browser boundaries.',
+    inputSchema: z.object({}),
+    async execute(client) {
+        const authState = client.hasApiKey()
+            ? 'Posterly API key is installed. Authenticated scheduling and connect tools are available.'
+            : 'No Posterly API key is installed. Only public signup tools are available until the user completes paid setup and gives this AI Posterly access.';
+        return [
+            'Posterly agent signup info',
+            '',
+            authState,
+            '',
+            'Pre-auth tools:',
+            '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
+            '- get_signup_session: polls checkout, payment, password, and agent-access status.',
+            '',
+            'After Posterly access is installed:',
+            '- whoami: confirm the paid Posterly account/workspace.',
+            '- create_connect_session: create a secure browser OAuth handoff for the social platform the user chooses.',
+            '- get_connect_session: poll the OAuth handoff until connected.',
+            '- create_post: schedule posts after the user confirms the account and content.',
+            '',
+            'Boundaries:',
+            '- The user pays in Stripe Checkout in their browser.',
+            '- The user sets their Posterly password in their browser.',
+            '- The user approves social OAuth in their browser.',
+            '- The AI should never ask for card details, Posterly passwords, social passwords, or OAuth codes.',
+        ].join('\n');
+    },
+};

package/dist/tools/get-connect-session.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getConnectSessionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        session_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        session_id: string;
+    }, {
+        session_id: string;
+    }>;
+    execute(client: PosterlyClient, input: {
+        session_id: string;
+    }): Promise<string>;
+};

package/dist/tools/get-connect-session.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export const getConnectSessionTool = {
+    name: 'get_connect_session',
+    description: 'Poll a Posterly connect session. Read status_message to tell the user what is happening; stop when status is connected, failed, cancelled, or expired.',
+    inputSchema: z.object({
+        session_id: z.string().describe('Connect session ID returned by create_connect_session.'),
+    }),
+    async execute(client, input) {
+        const result = await client.getConnectSession(input.session_id);
+        return formatConnectSession(result.connect_session);
+    },
+};
+function formatConnectSession(session) {
+    const connected = session.connected_count ?? session.connected_accounts?.length ?? 0;
+    return [
+        `Posterly connect session: ${session.id}`,
+        `Platform: ${session.platform}`,
+        `Status: ${session.status}`,
+        `Message: ${session.status_message}`,
+        `Connected accounts: ${connected}`,
+        session.error_message ? `Error: ${session.error_message}` : '',
+        `Expires: ${session.expires_at}`,
+        '',
+        `Raw connect session:\n${JSON.stringify(session, null, 2)}`,
+    ].filter(Boolean).join('\n');
+}

package/dist/tools/get-post-analytics.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+declare const presentationSchema: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
+type AnalyticsPresentation = z.infer<typeof presentationSchema>;
 export declare const getPostAnalyticsTool: {
     name: string;
     description: string;
@@ -9,18 +11,21 @@ export declare const getPostAnalyticsTool: {
         to: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodNumber>;
         offset: z.ZodOptional<z.ZodNumber>;
+        presentation: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
     }, "strip", z.ZodTypeAny, {
         account_id: number;
         limit?: number | undefined;
         offset?: number | undefined;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }, {
         account_id: number;
         limit?: number | undefined;
         offset?: number | undefined;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         account_id: number;
@@ -28,5 +33,7 @@ export declare const getPostAnalyticsTool: {
         to?: string;
         limit?: number;
         offset?: number;
+        presentation?: AnalyticsPresentation;
     }): Promise<string>;
 };
+export {};

package/dist/tools/get-post-analytics.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
 export const getPostAnalyticsTool = {
     name: 'get_post_analytics',
-    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first.',
+    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
     inputSchema: z.object({
         account_id: z
             .number()
@@ -21,61 +22,139 @@ export const getPostAnalyticsTool = {
             .optional()
             .describe('Number of posts to return (default 50, max 200)'),
         offset: z.number().min(0).optional().describe('Pagination offset'),
+        presentation: presentationSchema.describe('Output style: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
     }),
     async execute(client, input) {
         const result = await client.getPostAnalytics(input);
-        const { account, range, posts, total } = result;
-        if (posts.length === 0) {
-            return `No analytics found for @${account.username} (${account.platform}) between ${range.from} and ${range.to}.`;
-        }
-        const lines = [
-            `Post analytics for @${account.username} (${account.platform})`,
-            `Range: ${range.from} → ${range.to}  •  Showing ${posts.length} of ${total}`,
-            '',
-        ];
-        for (const p of posts) {
-            const postedAt = p.posted_at
-                ? new Date(p.posted_at).toLocaleString()
-                : 'unknown date';
-            const caption = p.caption_snippet
-                ? p.caption_snippet.length > 60
-                    ? `${p.caption_snippet.slice(0, 60)}…`
-                    : p.caption_snippet
-                : '(no caption)';
-            const metrics = [
-                `${p.likes} likes`,
-                `${p.comments} comments`,
-                `${p.reach.toLocaleString()} reach`,
-            ];
-            if (p.impressions)
-                metrics.push(`${p.impressions.toLocaleString()} impressions`);
-            if (p.saved)
-                metrics.push(`${p.saved} saved`);
-            if (p.shares)
-                metrics.push(`${p.shares} shares`);
-            if (p.plays)
-                metrics.push(`${p.plays.toLocaleString()} plays`);
-            if (account.platform === 'youtube' && p.total_watch_time_ms) {
-                metrics.push(`${Math.round(p.total_watch_time_ms / 60000).toLocaleString()} watch minutes`);
-            }
-            if (account.platform === 'youtube' && p.avg_watch_time_ms) {
-                metrics.push(`${Math.round(p.avg_watch_time_ms / 1000)}s avg view`);
-            }
-            if (p.url_link_clicks) {
-                metrics.push(account.platform === 'pinterest'
-                    ? `${p.url_link_clicks.toLocaleString()} outbound clicks`
-                    : `${p.url_link_clicks.toLocaleString()} link clicks`);
-            }
-            if (p.user_profile_clicks) {
-                metrics.push(account.platform === 'pinterest'
-                    ? `${p.user_profile_clicks.toLocaleString()} pin clicks`
-                    : `${p.user_profile_clicks.toLocaleString()} profile clicks`);
-            }
-            lines.push(`• [${postedAt}] ${caption}`);
-            lines.push(`  ${metrics.join(' • ')}`);
-            if (p.permalink)
-                lines.push(`  ${p.permalink}`);
-        }
-        return lines.join('\n');
+        return formatPostAnalytics(result, input.presentation || 'compact');
     },
 };
+function formatPostAnalytics(result, presentation) {
+    const { account, range, posts, total } = result;
+    if (posts.length === 0) {
+        return `No analytics found for ${accountLabel(account.username)} (${account.platform}) between ${range.from} and ${range.to}.`;
+    }
+    const totals = posts.reduce((acc, post) => {
+        acc.likes += post.likes || 0;
+        acc.comments += post.comments || 0;
+        acc.reach += post.reach || 0;
+        acc.impressions += post.impressions || 0;
+        acc.shares += post.shares || 0;
+        acc.saves += post.saved || 0;
+        return acc;
+    }, { likes: 0, comments: 0, reach: 0, impressions: 0, shares: 0, saves: 0 });
+    if (presentation === 'json') {
+        return JSON.stringify({
+            type: 'post_analytics',
+            account,
+            range,
+            returned: {
+                count: posts.length,
+                total,
+            },
+            totals,
+            posts,
+        }, null, 2);
+    }
+    if (presentation === 'table') {
+        return [
+            `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+            `_${account.platform} · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+            '',
+            '**Returned totals**',
+            markdownTable(['Likes', 'Comments', 'Reach', 'Impressions', 'Shares', 'Saves'], [[
+                    formatNumber(totals.likes),
+                    formatNumber(totals.comments),
+                    formatNumber(totals.reach),
+                    formatNumber(totals.impressions),
+                    formatNumber(totals.shares),
+                    formatNumber(totals.saves),
+                ]]),
+            '',
+            '**Posts**',
+            markdownTable(['Posted', 'Post', 'Caption', 'Reach', 'Likes', 'Comments', 'Extras'], posts.map((post) => [
+                dateTime(post.posted_at),
+                post.id ? String(post.id) : post.platform_media_id,
+                compact(post.caption_snippet, 70) || '(no caption)',
+                formatNumber(post.reach),
+                formatNumber(post.likes),
+                formatNumber(post.comments),
+                postExtras(account.platform, post),
+            ])),
+        ].join('\n');
+    }
+    const lines = [
+        `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+        `_${account.platform} · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+        '',
+        '**Returned totals**',
+        `- **Likes:** ${formatNumber(totals.likes)}`,
+        `- **Comments:** ${formatNumber(totals.comments)}`,
+        `- **Reach:** ${formatNumber(totals.reach)}`,
+        `- **Impressions:** ${formatNumber(totals.impressions)}`,
+        `- **Shares:** ${formatNumber(totals.shares)}`,
+        `- **Saves:** ${formatNumber(totals.saves)}`,
+        '',
+        '**Posts**',
+    ];
+    posts.forEach((post, index) => {
+        lines.push(`${index + 1}. **${compact(post.caption_snippet, 70) || '(no caption)'}**`);
+        lines.push(`   Posted: ${dateTime(post.posted_at)}`);
+        lines.push(`   Post ID: ${post.id ? String(post.id) : post.platform_media_id}`);
+        lines.push(`   Reach: ${formatNumber(post.reach)}`);
+        lines.push(`   Likes: ${formatNumber(post.likes)}`);
+        lines.push(`   Comments: ${formatNumber(post.comments)}`);
+        lines.push(`   Extras: ${postExtras(account.platform, post)}`);
+    });
+    return lines.join('\n');
+}
+function postExtras(platform, post) {
+    const metrics = [];
+    if (post.impressions)
+        metrics.push(`${formatNumber(post.impressions)} impressions`);
+    if (post.saved)
+        metrics.push(`${formatNumber(post.saved)} saved`);
+    if (post.shares)
+        metrics.push(`${formatNumber(post.shares)} shares`);
+    if (post.plays)
+        metrics.push(`${formatNumber(post.plays)} plays`);
+    if (platform === 'youtube' && post.total_watch_time_ms)
+        metrics.push(`${formatNumber(Math.round(post.total_watch_time_ms / 60000))} watch minutes`);
+    if (platform === 'youtube' && post.avg_watch_time_ms)
+        metrics.push(`${formatNumber(Math.round(post.avg_watch_time_ms / 1000))}s avg view`);
+    if (post.url_link_clicks)
+        metrics.push(platform === 'pinterest' ? `${formatNumber(post.url_link_clicks)} outbound clicks` : `${formatNumber(post.url_link_clicks)} link clicks`);
+    if (post.user_profile_clicks)
+        metrics.push(platform === 'pinterest' ? `${formatNumber(post.user_profile_clicks)} pin clicks` : `${formatNumber(post.user_profile_clicks)} profile clicks`);
+    if (post.permalink)
+        metrics.push(post.permalink);
+    return metrics.join(' · ') || 'n/a';
+}
+function accountLabel(username) {
+    if (!username)
+        return 'account';
+    return username.startsWith('@') || /\s/.test(username) ? username : `@${username}`;
+}
+function dateTime(value) {
+    if (!value)
+        return 'n/a';
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? value : date.toLocaleString();
+}
+function compact(value, maxLength) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    return text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 1))}…` : text;
+}
+function formatNumber(value) {
+    return value == null ? 'n/a' : value.toLocaleString();
+}
+function markdownTable(headers, rows) {
+    return [
+        `| ${headers.map(escapeCell).join(' | ')} |`,
+        `| ${headers.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+    ].join('\n');
+}
+function escapeCell(value) {
+    return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}

package/dist/tools/get-signup-session.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getSignupSessionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        session_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        session_id: string;
+    }, {
+        session_id: string;
+    }>;
+    execute(client: PosterlyClient, input: {
+        session_id: string;
+    }): Promise<string>;
+};

package/dist/tools/get-signup-session.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export const getSignupSessionTool = {
+    name: 'get_signup_session',
+    description: 'Poll a public Posterly signup session created by start_signup. Use this to narrate checkout, payment, password setup, and agent access status before a Posterly API key is installed.',
+    inputSchema: z.object({
+        session_id: z
+            .string()
+            .min(8)
+            .describe('Signup session ID returned by start_signup, usually the Stripe checkout session ID.'),
+    }),
+    async execute(client, input) {
+        const result = await client.getSignupSession(input.session_id);
+        return formatSignupSession(result.signup_session);
+    },
+};
+function formatSignupSession(session) {
+    const nextAction = session.next_action;
+    const checkoutRedirectUrl = session.checkout_redirect_url || stringFromRecord(session.links, 'checkout_redirect_url');
+    const checkoutUrl = stringFromRecord(session.links, 'checkout_url');
+    const passwordUrl = stringFromRecord(session.links, 'password_setup_url');
+    const completeUrl = stringFromRecord(session.links, 'complete_url');
+    const lines = [
+        `Posterly signup session: ${session.id}`,
+        `Status: ${session.status}`,
+        session.status_message ? `Message: ${session.status_message}` : '',
+        nextAction?.label ? `Next action: ${nextAction.label}` : '',
+        nextAction?.description ? `Next action detail: ${nextAction.description}` : '',
+        checkoutRedirectUrl ? `Checkout handoff URL: ${checkoutRedirectUrl}` : '',
+        checkoutUrl ? `Checkout URL: ${checkoutUrl}` : '',
+        passwordUrl ? `Password setup URL: ${passwordUrl}` : '',
+        completeUrl ? `Completion URL: ${completeUrl}` : '',
+        '',
+        guidanceForStatus(session.status),
+        session.agent_next_steps?.length
+            ? `Agent next steps:\n${session.agent_next_steps.map((step, index) => `${index + 1}. ${step}`).join('\n')}`
+            : '',
+        '',
+        `Raw signup session:\n${JSON.stringify(session, null, 2)}`,
+    ];
+    return lines.filter(Boolean).join('\n');
+}
+function stringFromRecord(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : null;
+}
+function guidanceForStatus(status) {
+    switch (status) {
+        case 'checkout_pending':
+            return 'Tell the user checkout is still pending. Keep polling; do not ask for card details.';
+        case 'checkout_expired':
+            return 'Tell the user checkout expired and offer to call start_signup again.';
+        case 'payment_confirmed':
+            return 'Tell the user payment is confirmed and Posterly is preparing access. Keep polling.';
+        case 'password_required':
+            return 'Tell the user Posterly has sent a password setup email. They need to open that email and set a password in the browser.';
+        case 'authorize_agent':
+            return 'Tell the user Posterly is ready for agent authorization. Send them the provided authorization or completion link if one is present.';
+        case 'agent_access_required':
+            return 'Tell the user API access is active, but this AI still needs Posterly access. Ask them to paste the Posterly MCP/API setup instructions here or install the Posterly MCP server, then continue with social account connection.';
+        case 'api_access_active':
+            return 'Posterly API access is active. Ask which social account the user wants to connect first, then create a connect session.';
+        default:
+            return 'Explain the current status to the user and keep polling unless the session is terminal.';
+    }
+}

package/dist/tools/get-video-job.d.ts

@@ -8,11 +8,11 @@ export declare const getVideoJobTool: {
         status: z.ZodOptional<z.ZodEnum<["pending", "processing", "completed", "failed", "dismissed"]>>;
         limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
-        status?: "pending" | "processing" | "completed" | "failed" | "dismissed" | undefined;
+        status?: "failed" | "pending" | "processing" | "completed" | "dismissed" | undefined;
         limit?: number | undefined;
         job_id?: string | undefined;
     }, {
-        status?: "pending" | "processing" | "completed" | "failed" | "dismissed" | undefined;
+        status?: "failed" | "pending" | "processing" | "completed" | "dismissed" | undefined;
         limit?: number | undefined;
         job_id?: string | undefined;
     }>;

package/dist/tools/list-posts.d.ts

@@ -10,15 +10,15 @@ export declare const listPostsTool: {
         limit: z.ZodOptional<z.ZodNumber>;
         workspace_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
+        status?: string | undefined;
         workspace_id?: string | undefined;
         platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "linkedin" | "youtube" | "pinterest" | "threads" | "google_business" | "telegram" | "bluesky" | "gmb" | "google-business" | "google_business_profile" | "x" | undefined;
-        status?: string | undefined;
         account_id?: string | undefined;
         limit?: number | undefined;
     }, {
+        status?: string | undefined;
         workspace_id?: string | undefined;
         platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "linkedin" | "youtube" | "pinterest" | "threads" | "google_business" | "telegram" | "bluesky" | "gmb" | "google-business" | "google_business_profile" | "x" | undefined;
-        status?: string | undefined;
         account_id?: string | undefined;
         limit?: number | undefined;
     }>;