posterly-mcp-server 0.44.0 → 0.45.0

package/dist/tools/list-analytics.js

@@ -0,0 +1,393 @@
+import { z } from 'zod';
+import { formatDateTime, mdEmpty, mdKeyValue, mdSection, mdTitle, truncateText } from '../lib/format.js';
+import { validateArgs } from '../lib/tool-runtime.js';
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
+export const listAnalyticsTool = {
+    name: 'list_analytics',
+    description: 'Analytics for connected social accounts (Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads). view=accounts (account_id): daily snapshots and a period summary with platform-native display_metrics labels. view=posts (account_id): per-post likes, comments/replies, reach, impressions/views, saves, shares, reposts, quotes, plays, clicks, and watch time, most recent first, with limit/offset. view=insights: per-post feedback insights with a performance tier (great/good/mixed/poor), diagnosis, next action, and baseline, filtered by account_id, post_id, or checkpoint (1h, 6h, 24h, 72h, 7d); read-only, Pro plan or higher. presentation (accounts and posts): compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
+    inputSchema: z.object({
+        view: z.enum(['accounts', 'posts', 'insights']).describe('accounts, posts, or insights.'),
+        account_id: z
+            .union([z.number(), z.string()])
+            .optional()
+            .describe('The social account ID (from list_accounts). Required for accounts and posts; optional filter for insights.'),
+        from: z
+            .string()
+            .optional()
+            .describe('accounts and posts: start date (ISO date, e.g. 2026-03-19). Defaults to 30 days ago.'),
+        to: z
+            .string()
+            .optional()
+            .describe('accounts and posts: end date (ISO date). Defaults to today.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe('posts: number of posts (default 50, max 200). insights: max insights (default 20, max 100).'),
+        offset: z.number().min(0).optional().describe('posts: pagination offset'),
+        post_id: z.number().int().positive().optional().describe('insights: filter to one post ID.'),
+        checkpoint: z
+            .enum(['1h', '6h', '24h', '72h', '7d'])
+            .optional()
+            .describe('insights: filter to one checkpoint after publish.'),
+        presentation: presentationSchema.describe('accounts and posts: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
+    }),
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        get_account_analytics: z.object({
+            account_id: z.number(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            presentation: presentationSchema,
+        }),
+        get_post_analytics: z.object({
+            account_id: z.number(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            limit: z.number().min(1).max(200).optional(),
+            offset: z.number().min(0).optional(),
+            presentation: presentationSchema,
+        }),
+        get_post_insights: z.object({
+            account_id: z.union([z.string(), z.number()]).optional(),
+            post_id: z.number().int().positive().optional(),
+            checkpoint: z.enum(['1h', '6h', '24h', '72h', '7d']).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+    },
+    async execute(client, input, ctx) {
+        const { mode, args } = validateArgs(ctx, 'list_analytics', input);
+        if (mode === 'accounts') {
+            const result = await client.getAccountAnalytics(args);
+            return formatAccountAnalytics(result, args.presentation || 'compact');
+        }
+        if (mode === 'posts') {
+            const result = await client.getPostAnalytics(args);
+            return formatPostAnalytics(result, args.presentation || 'compact');
+        }
+        return postInsights(client, args);
+    },
+};
+async function postInsights(client, input) {
+    const { insights } = await client.getPostInsights(input);
+    if (!insights.length) {
+        return mdEmpty('feedback insights', 'No per-post feedback insights are available for these filters yet. Insights appear as posts hit their 1h, 6h, 24h, 72h, and 7d checkpoints.');
+    }
+    const blocks = insights.map((insight) => {
+        const heading = `${insight.title || 'Insight'} (${insight.performance_tier}, ${insight.checkpoint})`;
+        return mdSection(heading, mdKeyValue([
+            ['Post ID', insight.post_id],
+            ['Platform', insight.platform],
+            ['Account', insight.username ? `@${insight.username}` : String(insight.social_account_id)],
+            ['Diagnosis', truncateText(insight.diagnosis, 220)],
+            ['Next action', truncateText(insight.next_action, 220)],
+            ['Impact score', insight.impact_score],
+            ['Confidence', insight.confidence],
+            ['Published', formatDateTime(insight.published_at)],
+            ['Permalink', insight.permalink || undefined],
+        ]));
+    });
+    return [mdTitle(`Post feedback insights (${insights.length})`), ...blocks].join('\n\n');
+}
+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', 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)],
+        ];
+    }
+    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 formatNumber(value) {
+    return value == null ? 'n/a' : 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>');
+}
+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.reposts += post.reposts || 0;
+        acc.quotes += post.quotes || 0;
+        acc.saves += post.saved || 0;
+        return acc;
+    }, { likes: 0, comments: 0, reach: 0, impressions: 0, shares: 0, reposts: 0, quotes: 0, saves: 0 });
+    const isThreads = account.platform === 'threads';
+    if (presentation === 'json') {
+        return JSON.stringify({
+            type: 'post_analytics',
+            account,
+            range,
+            returned: {
+                count: posts.length,
+                total,
+            },
+            totals,
+            posts,
+        }, null, 2);
+    }
+    if (presentation === 'table') {
+        if (isThreads) {
+            return [
+                `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+                `_Threads · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+                '',
+                '**Returned totals**',
+                markdownTable(['Views', 'Likes', 'Replies', 'Reposts', 'Quotes', 'Shares'], [[
+                        formatNumber(totals.impressions),
+                        formatNumber(totals.likes),
+                        formatNumber(totals.comments),
+                        formatNumber(totals.reposts),
+                        formatNumber(totals.quotes),
+                        formatNumber(totals.shares),
+                    ]]),
+                '',
+                '**Posts**',
+                markdownTable(['Posted', 'Post', 'Caption', 'Views', 'Likes', 'Replies', 'Reposts', 'Quotes', 'Shares'], 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.impressions),
+                    formatNumber(post.likes),
+                    formatNumber(post.comments),
+                    formatNumber(post.reposts),
+                    formatNumber(post.quotes),
+                    formatNumber(post.shares),
+                ])),
+            ].join('\n');
+        }
+        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**',
+    ];
+    if (isThreads) {
+        const threadLines = [
+            `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+            `_Threads · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+            '',
+            '**Returned totals**',
+            `- **Views:** ${formatNumber(totals.impressions)}`,
+            `- **Likes:** ${formatNumber(totals.likes)}`,
+            `- **Replies:** ${formatNumber(totals.comments)}`,
+            `- **Reposts:** ${formatNumber(totals.reposts)}`,
+            `- **Quotes:** ${formatNumber(totals.quotes)}`,
+            `- **Shares:** ${formatNumber(totals.shares)}`,
+            '',
+            '**Posts**',
+        ];
+        posts.forEach((post, index) => {
+            threadLines.push(`${index + 1}. **${compact(post.caption_snippet, 70) || '(no caption)'}**`);
+            threadLines.push(`   Posted: ${dateTime(post.posted_at)}`);
+            threadLines.push(`   Post ID: ${post.id ? String(post.id) : post.platform_media_id}`);
+            threadLines.push(`   Views: ${formatNumber(post.impressions)}`);
+            threadLines.push(`   Likes: ${formatNumber(post.likes)}`);
+            threadLines.push(`   Replies: ${formatNumber(post.comments)}`);
+            threadLines.push(`   Reposts: ${formatNumber(post.reposts)}`);
+            threadLines.push(`   Quotes: ${formatNumber(post.quotes)}`);
+            threadLines.push(`   Shares: ${formatNumber(post.shares)}`);
+            if (post.permalink)
+                threadLines.push(`   Permalink: ${post.permalink}`);
+        });
+        return threadLines.join('\n');
+    }
+    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 (platform !== 'threads' && 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 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;
+}

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

@@ -1,16 +1,51 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { type ToolContext } from '../lib/tool-runtime.js';
+type ListBrandsInput = {
+    view?: 'brands' | 'brand' | 'accounts' | 'profile';
+    brand_id?: string;
+    workspace_id?: string;
+};
 export declare const listBrandsTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
+        view: z.ZodOptional<z.ZodEnum<["brands", "brand", "accounts", "profile"]>>;
+        brand_id: z.ZodOptional<z.ZodString>;
         workspace_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
+        brand_id?: string | undefined;
+        view?: "accounts" | "brands" | "brand" | "profile" | undefined;
     }, {
         workspace_id?: string | undefined;
+        brand_id?: string | undefined;
+        view?: "accounts" | "brands" | "brand" | "profile" | undefined;
     }>;
-    execute(client: PosterlyClient, input: {
-        workspace_id?: string;
-    }): Promise<string>;
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        get_brand: z.ZodObject<{
+            brand_id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            brand_id: string;
+        }, {
+            brand_id: string;
+        }>;
+        list_brand_accounts: z.ZodObject<{
+            brand_id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            brand_id: string;
+        }, {
+            brand_id: string;
+        }>;
+        get_brand_profile: z.ZodObject<{
+            brand_id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            brand_id: string;
+        }, {
+            brand_id: string;
+        }>;
+    };
+    execute(client: PosterlyClient, input: ListBrandsInput, ctx: ToolContext): Promise<string>;
 };
+export {};

package/dist/tools/list-brands.js

@@ -1,30 +1,148 @@
 import { z } from 'zod';
-import { code, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
+import { code, compactText, formatDateTime, mdEmpty, mdKeyValue, mdLearnedVoice, mdSection, mdTable, mdTitle } from '../lib/format.js';
+import { validateArgs } from '../lib/tool-runtime.js';
 export const listBrandsTool = {
     name: 'list_brands',
-    description: 'List brands/clients the caller can access. Returns each brand ID, name, workspace ID, source, and how many social accounts are currently assigned to it.',
+    description: 'Brands (clients) and their saved context. view=brands (default): brands the caller can access with brand ID, name, workspace ID, source, and how many social accounts are assigned (optional workspace_id). view=brand (brand_id): one brand with its workspace, source, and linked legacy brand group. view=accounts (brand_id): the connected social accounts assigned to the brand; use it when a user refers to a brand name rather than an account handle. view=profile (brand_id): voice and tone, audience, keywords, dos and don’ts, visual notes, and other saved brand context.',
     inputSchema: z.object({
+        view: z
+            .enum(['brands', 'brand', 'accounts', 'profile'])
+            .optional()
+            .describe('brands (default), brand, accounts, or profile.'),
+        brand_id: z.string().optional().describe('The brand ID (from view=brands). Required for brand, accounts, and profile.'),
         workspace_id: z
             .string()
             .optional()
-            .describe('Filter to brands in a specific workspace (get IDs via whoami).'),
+            .describe('view=brands: filter to brands in a specific workspace (get IDs via whoami).'),
     }),
-    async execute(client, input) {
-        const brands = await client.listBrands({ workspace_id: input.workspace_id });
-        if (brands.length === 0) {
-            return input.workspace_id
-                ? mdEmpty('brands', 'This workspace does not have any brands or clients yet.')
-                : mdEmpty('brands', 'No brands or clients were found for this API key.', 'Create a brand in the posterly dashboard, then run this again.');
-        }
-        return [
-            mdTitle(`Brands (${brands.length})`),
-            mdTable(['Brand', 'Brand ID', 'Accounts', 'Source', 'Workspace'], brands.map((brand) => [
-                brand.name,
-                code(brand.id),
-                brand.account_count,
-                brand.source,
-                brand.workspace_id ? code(brand.workspace_id) : 'default',
-            ])),
-        ].join('\n\n');
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        get_brand: z.object({ brand_id: z.string() }),
+        list_brand_accounts: z.object({ brand_id: z.string() }),
+        get_brand_profile: z.object({ brand_id: z.string() }),
+    },
+    async execute(client, input, ctx) {
+        const { mode, args } = validateArgs(ctx, 'list_brands', input);
+        if (mode === 'brand')
+            return brand(client, args);
+        if (mode === 'accounts')
+            return brandAccounts(client, args);
+        if (mode === 'profile')
+            return brandProfile(client, args);
+        return brands(client, args);
     },
 };
+async function brands(client, input) {
+    const brands = await client.listBrands({ workspace_id: input.workspace_id });
+    if (brands.length === 0) {
+        return input.workspace_id
+            ? mdEmpty('brands', 'This workspace does not have any brands or clients yet.')
+            : mdEmpty('brands', 'No brands or clients were found for this API key.', 'Create a brand in the posterly dashboard, then run this again.');
+    }
+    return [
+        mdTitle(`Brands (${brands.length})`),
+        mdTable(['Brand', 'Brand ID', 'Accounts', 'Source', 'Workspace'], brands.map((brand) => [
+            brand.name,
+            code(brand.id),
+            brand.account_count,
+            brand.source,
+            brand.workspace_id ? code(brand.workspace_id) : 'default',
+        ])),
+    ].join('\n\n');
+}
+async function brand(client, input) {
+    const result = await client.getBrand(input.brand_id);
+    const brand = result.brand;
+    return [
+        mdTitle(`Brand: ${brand.name}`),
+        mdKeyValue([
+            ['Brand ID', code(brand.id)],
+            ['Source', brand.source],
+            ['Workspace', brand.workspace_id ? code(brand.workspace_id) : 'n/a'],
+            ['Accounts assigned', brand.account_count ?? 0],
+            ['Workspace client ID', brand.workspace_client_id ? code(brand.workspace_client_id) : undefined],
+            ['Legacy brand group ID', brand.legacy_brand_group_id ? code(brand.legacy_brand_group_id) : undefined],
+            ['Created', formatDateTime(brand.created_at)],
+            ['Updated', formatDateTime(brand.updated_at)],
+        ]),
+    ].join('\n\n');
+}
+async function brandAccounts(client, input) {
+    const accounts = await client.listBrandAccounts(input.brand_id);
+    if (accounts.length === 0) {
+        return mdEmpty('brand accounts', 'No social accounts are currently assigned to this brand.');
+    }
+    return [
+        mdTitle(`Brand accounts (${accounts.length})`),
+        mdTable(['Platform', 'Account', 'Account ID', 'Workspace'], accounts.map((account) => [
+            account.platform,
+            `@${account.username}`,
+            code(account.id),
+            account.workspace_id ? code(account.workspace_id) : 'default',
+        ])),
+    ].join('\n\n');
+}
+async function brandProfile(client, input) {
+    const result = await client.getBrandProfile(input.brand_id);
+    const profile = result.brand_profile;
+    const profileBody = [
+        mdKeyValue([
+            ['Source', profile.source],
+            ['Profile ID', profile.id ? code(profile.id) : undefined],
+            ['Workspace client ID', profile.workspace_client_id ? code(profile.workspace_client_id) : undefined],
+            ['Legacy brand group ID', profile.brand_group_id ? code(profile.brand_group_id) : undefined],
+            ['Logo', profile.logo_url],
+            ['Last refreshed', profile.last_context_refresh_at ? formatDateTime(profile.last_context_refresh_at) : undefined],
+        ]),
+        mdSection('Voice and audience', mdKeyValue([
+            ['Tone of voice', compactText(profile.tone_of_voice, 180)],
+            ['Audience', compactText(profile.audience, 180)],
+            ['Brand values', compactText(profile.brand_values, 180)],
+            ['Brand story', compactText(formatStructuredValue(profile.brand_story), 240)],
+        ])),
+        mdSection('Guidance', mdKeyValue([
+            ['Custom instructions', compactText(profile.custom_instructions, 240)],
+            ['Keywords', formatStructuredValue(profile.keywords)],
+            ['Competitors', formatStructuredValue(profile.competitors)],
+            ['Do / Don’ts', formatStructuredValue(profile.do_donts)],
+            ['Topics to cover', formatStructuredValue(profile.topics_to_cover)],
+            ['Topics to avoid', formatStructuredValue(profile.topics_to_avoid)],
+        ])),
+        mdSection('Creative references', mdKeyValue([
+            ['Visual guidelines', formatStructuredValue(profile.visual_guidelines)],
+            ['Example posts', formatStructuredValue(profile.example_posts)],
+            ['Voice examples', formatStructuredValue(profile.voice_examples)],
+        ])),
+    ].filter(Boolean).join('\n\n');
+    const learnedVoices = (Array.isArray(profile.learned_voice) ? profile.learned_voice : []);
+    const learnedBody = learnedVoices.length
+        ? mdSection('Learned voice (from published captions)', learnedVoices.map((voice) => mdLearnedVoice(voice)).filter(Boolean).join('\n\n'))
+        : '';
+    return [
+        mdTitle(`Brand profile: ${profile.brand_name}`),
+        profileBody || 'No extended brand profile fields have been saved yet.',
+        learnedBody ||
+            '_No learned voice yet. posterly learns each account’s voice automatically once it has enough published posts._',
+    ].filter(Boolean).join('\n\n');
+}
+function formatStructuredValue(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return null;
+        return value
+            .map((item) => formatStructuredValue(item) || JSON.stringify(item))
+            .filter(Boolean)
+            .join(' | ');
+    }
+    if (typeof value === 'object') {
+        const json = JSON.stringify(value);
+        return json === '{}' ? null : json;
+    }
+    return String(value);
+}