@collage-dam/mcp-server 0.1.0

package/dist/tools/get-embed-code.d.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+import type { CollageClient } from '../client.js';
+/**
+ * Narrow surface used by the handler — kept minimal so tests can stub
+ * without instantiating the full CollageClient.
+ */
+export type GetEmbedCodeClient = Pick<CollageClient, 'generateEmbedCode'>;
+export declare const EmbedSizePresetSchema: z.ZodEnum<["small", "medium", "large", "responsive"]>;
+export type EmbedSizePreset = z.infer<typeof EmbedSizePresetSchema>;
+/**
+ * Inner object schema — exported for the MCP server registration which
+ * needs the raw `.shape` (refined schemas don't expose it directly).
+ */
+export declare const GetEmbedCodeInputObjectSchema: z.ZodObject<{
+    /** Target a single asset for the embed. */
+    asset_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    /**
+     * Phase-1 limitation: Collage does not expose a collection-level
+     * embed endpoint. Accepted at the schema level so the error
+     * surfaces at runtime as VALIDATION rather than a confusing 404.
+     */
+    collection_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    size: z.ZodOptional<z.ZodEnum<["small", "medium", "large", "responsive"]>>;
+    /** Only meaningful for video assets. Ignored otherwise. */
+    autoplay: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    asset_id?: string | number | undefined;
+    collection_id?: string | number | undefined;
+    size?: "small" | "medium" | "large" | "responsive" | undefined;
+    autoplay?: boolean | undefined;
+}, {
+    asset_id?: string | number | undefined;
+    collection_id?: string | number | undefined;
+    size?: "small" | "medium" | "large" | "responsive" | undefined;
+    autoplay?: boolean | undefined;
+}>;
+export declare const GetEmbedCodeInputSchema: z.ZodEffects<z.ZodObject<{
+    /** Target a single asset for the embed. */
+    asset_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    /**
+     * Phase-1 limitation: Collage does not expose a collection-level
+     * embed endpoint. Accepted at the schema level so the error
+     * surfaces at runtime as VALIDATION rather than a confusing 404.
+     */
+    collection_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    size: z.ZodOptional<z.ZodEnum<["small", "medium", "large", "responsive"]>>;
+    /** Only meaningful for video assets. Ignored otherwise. */
+    autoplay: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    asset_id?: string | number | undefined;
+    collection_id?: string | number | undefined;
+    size?: "small" | "medium" | "large" | "responsive" | undefined;
+    autoplay?: boolean | undefined;
+}, {
+    asset_id?: string | number | undefined;
+    collection_id?: string | number | undefined;
+    size?: "small" | "medium" | "large" | "responsive" | undefined;
+    autoplay?: boolean | undefined;
+}>, {
+    asset_id?: string | number | undefined;
+    collection_id?: string | number | undefined;
+    size?: "small" | "medium" | "large" | "responsive" | undefined;
+    autoplay?: boolean | undefined;
+}, {
+    asset_id?: string | number | undefined;
+    collection_id?: string | number | undefined;
+    size?: "small" | "medium" | "large" | "responsive" | undefined;
+    autoplay?: boolean | undefined;
+}>;
+export type GetEmbedCodeInput = z.infer<typeof GetEmbedCodeInputSchema>;
+export declare const GetEmbedCodeOutputSchema: z.ZodObject<{
+    asset_id: z.ZodString;
+    size: z.ZodEnum<["small", "medium", "large", "responsive"]>;
+    autoplay: z.ZodBoolean;
+    embed_code: z.ZodString;
+    embed_code_raw: z.ZodString;
+    preview: z.ZodObject<{
+        width: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        height: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        autoplay_applied: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        height: string | number;
+        width: string | number;
+        autoplay_applied: boolean;
+    }, {
+        height: string | number;
+        width: string | number;
+        autoplay_applied: boolean;
+    }>;
+    request_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    request_id: string;
+    embed_code: string;
+    asset_id: string;
+    preview: {
+        height: string | number;
+        width: string | number;
+        autoplay_applied: boolean;
+    };
+    size: "small" | "medium" | "large" | "responsive";
+    autoplay: boolean;
+    embed_code_raw: string;
+}, {
+    request_id: string;
+    embed_code: string;
+    asset_id: string;
+    preview: {
+        height: string | number;
+        width: string | number;
+        autoplay_applied: boolean;
+    };
+    size: "small" | "medium" | "large" | "responsive";
+    autoplay: boolean;
+    embed_code_raw: string;
+}>;
+export type GetEmbedCodeOutput = z.infer<typeof GetEmbedCodeOutputSchema>;
+export declare const GET_EMBED_CODE_DESCRIPTION: string;
+interface SizeDimensions {
+    width: number | string;
+    height: number | string;
+}
+export declare function buildGetEmbedCodeHandler(client: GetEmbedCodeClient): (args: GetEmbedCodeInput) => Promise<{
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        };
+        request_id?: undefined;
+    };
+} | {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        };
+        request_id: string;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        request_id: string;
+        embed_code: string;
+        asset_id: string;
+        preview: {
+            height: string | number;
+            width: string | number;
+            autoplay_applied: boolean;
+        };
+        size: "small" | "medium" | "large" | "responsive";
+        autoplay: boolean;
+        embed_code_raw: string;
+    };
+    isError?: undefined;
+}>;
+/**
+ * Rewrite the iframe `width`/`height` attributes (case-insensitive) to the
+ * chosen size preset. If the snippet doesn't contain an `<iframe ...>`
+ * opening tag, returns the input unchanged — callers always also receive
+ * the raw markup under `embed_code_raw`.
+ */
+export declare function applySizePreset(html: string, dims: SizeDimensions): string;
+/**
+ * Append `autoplay=1` to the iframe's `src` querystring. If no `src`
+ * attribute is present (or the snippet has no iframe), returns the input
+ * unchanged with `applied: false`.
+ */
+export declare function applyAutoplay(html: string): {
+    html: string;
+    applied: boolean;
+};
+export {};
+//# sourceMappingURL=get-embed-code.d.ts.map

package/dist/tools/get-embed-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-embed-code.d.ts","sourceRoot":"","sources":["../../src/tools/get-embed-code.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;AAM1E,eAAO,MAAM,qBAAqB,uDAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,6BAA6B;IACxC,2CAA2C;;IAE3C;;;;OAIG;;;IAGH,2DAA2D;;;;;;;;;;;;EAE3D,CAAC;AAEH,eAAO,MAAM,uBAAuB;IAblC,2CAA2C;;IAE3C;;;;OAIG;;;IAGH,2DAA2D;;;;;;;;;;;;;;;;;;;;;;EAa1D,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,0BAA0B,QAMT,CAAC;AAI/B,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAWD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,IACnD,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFtC;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAa1E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAmB9E"}

package/dist/tools/get-embed-code.js

@@ -0,0 +1,214 @@
+// ── get_embed_code (read-only) ───────────────────────────────────────
+// Generates an embeddable HTML snippet for a single Collage asset.
+// Read-only — no dry-run wrapping (the upstream computes the snippet from
+// existing state and idempotently caches it; calling this does not create
+// or modify resources from the caller's perspective).
+//
+// Upstream surface (verified via Admin-Frontend
+// `components/dam/Dialogs/ShareAssetDialog/index.vue:476`):
+//   GET digital-assets/{asset_id}/generate-embed-code
+//   response: { data: { embed_code: '<iframe ...>' } }
+//
+// Collection-level embed: NOT supported by Collage's REST API today. The
+// Admin-Frontend's own `ShareAssetDialog` only renders the embed tab when
+// a single asset is selected (`getEmbedLink` reads `this.files[0].id`).
+// We surface a typed VALIDATION error if the caller passes a collection
+// target — recorded as a Phase 1 limitation.
+//
+// `size` and `autoplay` are *client-side wrappers* — the upstream returns a
+// fixed iframe markup, and the Admin-Frontend does not expose either knob.
+// We accept them at the tool surface so prompt-language stays natural,
+// then post-process the snippet: rewrite the iframe `width`/`height` to
+// match the chosen size preset and append `autoplay=1` to the iframe's
+// `src` querystring when `autoplay=true` and the asset is a video. The
+// raw upstream markup is also returned under `embed_code_raw` so callers
+// can compare or fall back.
+import { z } from 'zod';
+import { createToolError } from '../conventions/errors.js';
+import { IdSchema } from '../types.js';
+// ── Tool I/O Schema ──────────────────────────────────────────────────
+export const EmbedSizePresetSchema = z.enum([
+    'small',
+    'medium',
+    'large',
+    'responsive',
+]);
+/**
+ * Inner object schema — exported for the MCP server registration which
+ * needs the raw `.shape` (refined schemas don't expose it directly).
+ */
+export const GetEmbedCodeInputObjectSchema = z.object({
+    /** Target a single asset for the embed. */
+    asset_id: IdSchema.optional(),
+    /**
+     * Phase-1 limitation: Collage does not expose a collection-level
+     * embed endpoint. Accepted at the schema level so the error
+     * surfaces at runtime as VALIDATION rather than a confusing 404.
+     */
+    collection_id: IdSchema.optional(),
+    size: EmbedSizePresetSchema.optional(),
+    /** Only meaningful for video assets. Ignored otherwise. */
+    autoplay: z.boolean().optional(),
+});
+export const GetEmbedCodeInputSchema = GetEmbedCodeInputObjectSchema
+    .refine((input) => [input.asset_id !== undefined, input.collection_id !== undefined].filter(Boolean).length === 1, {
+    message: 'Provide exactly one of `asset_id` or `collection_id`.',
+});
+export const GetEmbedCodeOutputSchema = z.object({
+    asset_id: z.string(),
+    size: EmbedSizePresetSchema,
+    autoplay: z.boolean(),
+    embed_code: z.string(),
+    embed_code_raw: z.string(),
+    preview: z.object({
+        width: z.union([z.number(), z.string()]),
+        height: z.union([z.number(), z.string()]),
+        autoplay_applied: z.boolean(),
+    }),
+    request_id: z.string(),
+});
+export const GET_EMBED_CODE_DESCRIPTION = 'Generate an embeddable HTML snippet for a single Collage asset. ' +
+    'Optional `size` preset (`small`, `medium`, `large`, `responsive`) and ' +
+    '`autoplay` flag (only meaningful for video assets). Returns the ' +
+    'snippet plus a preview of how it will render. Read-only — no ' +
+    'confirmation token needed. Collection-level embeds are not supported ' +
+    'by the upstream API today.';
+const SIZE_PRESETS = {
+    small: { width: 320, height: 240 },
+    medium: { width: 640, height: 480 },
+    large: { width: 1280, height: 720 },
+    responsive: { width: '100%', height: '100%' },
+};
+// ── Handler ──────────────────────────────────────────────────────────
+export function buildGetEmbedCodeHandler(client) {
+    return async (args) => {
+        if (args.collection_id !== undefined && args.asset_id === undefined) {
+            const error = createToolError('VALIDATION', 'Collection-level embed codes are not supported by the Collage API today. ' +
+                'Pass `asset_id` instead. Track Phase-2 enhancement under the ' +
+                'Share Link, Embed & Distribution Tools spec.');
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `get_embed_code failed: ${error.code} — ${error.message}`,
+                    },
+                ],
+                structuredContent: { error },
+            };
+        }
+        if (args.asset_id === undefined) {
+            const error = createToolError('VALIDATION', '`asset_id` is required to generate an embed code.');
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `get_embed_code failed: ${error.code} — ${error.message}`,
+                    },
+                ],
+                structuredContent: { error },
+            };
+        }
+        const assetId = String(args.asset_id);
+        const size = args.size ?? 'medium';
+        const autoplay = args.autoplay === true;
+        const result = await client.generateEmbedCode(assetId);
+        if (!result.ok) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `get_embed_code failed: ${result.error.code} — ${result.error.message}`,
+                    },
+                ],
+                structuredContent: {
+                    error: result.error,
+                    request_id: result.request_id,
+                },
+            };
+        }
+        const raw = result.data.embed_code;
+        const dims = SIZE_PRESETS[size];
+        const sized = applySizePreset(raw, dims);
+        const { html: finalHtml, applied: autoplayApplied } = autoplay
+            ? applyAutoplay(sized)
+            : { html: sized, applied: false };
+        const output = {
+            asset_id: assetId,
+            size,
+            autoplay,
+            embed_code: finalHtml,
+            embed_code_raw: raw,
+            preview: {
+                width: dims.width,
+                height: dims.height,
+                autoplay_applied: autoplayApplied,
+            },
+            request_id: result.request_id,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(output, null, 2),
+                },
+            ],
+            structuredContent: output,
+        };
+    };
+}
+// ── Snippet Post-Processors ──────────────────────────────────────────
+/**
+ * Rewrite the iframe `width`/`height` attributes (case-insensitive) to the
+ * chosen size preset. If the snippet doesn't contain an `<iframe ...>`
+ * opening tag, returns the input unchanged — callers always also receive
+ * the raw markup under `embed_code_raw`.
+ */
+export function applySizePreset(html, dims) {
+    const iframeMatch = html.match(/<iframe\b[^>]*>/i);
+    if (iframeMatch === null || iframeMatch.index === undefined)
+        return html;
+    const tag = iframeMatch[0];
+    let updated = tag;
+    updated = setOrInsertAttr(updated, 'width', String(dims.width));
+    updated = setOrInsertAttr(updated, 'height', String(dims.height));
+    return (html.slice(0, iframeMatch.index) +
+        updated +
+        html.slice(iframeMatch.index + tag.length));
+}
+/**
+ * Append `autoplay=1` to the iframe's `src` querystring. If no `src`
+ * attribute is present (or the snippet has no iframe), returns the input
+ * unchanged with `applied: false`.
+ */
+export function applyAutoplay(html) {
+    const iframeMatch = html.match(/<iframe\b[^>]*>/i);
+    if (iframeMatch === null || iframeMatch.index === undefined) {
+        return { html, applied: false };
+    }
+    const tag = iframeMatch[0];
+    const srcMatch = tag.match(/\bsrc\s*=\s*"([^"]*)"/i);
+    if (srcMatch === null)
+        return { html, applied: false };
+    const src = srcMatch[1] ?? '';
+    if (/\bautoplay\s*=\s*1\b/i.test(src)) {
+        return { html, applied: true };
+    }
+    const newSrc = src.includes('?') ? `${src}&autoplay=1` : `${src}?autoplay=1`;
+    const newTag = tag.replace(srcMatch[0], `src="${newSrc}"`);
+    const newHtml = html.slice(0, iframeMatch.index) +
+        newTag +
+        html.slice(iframeMatch.index + tag.length);
+    return { html: newHtml, applied: true };
+}
+function setOrInsertAttr(tag, attr, value) {
+    const re = new RegExp(`\\b${attr}\\s*=\\s*"[^"]*"`, 'i');
+    if (re.test(tag)) {
+        return tag.replace(re, `${attr}="${value}"`);
+    }
+    // Insert before the closing `>` (or `/>`).
+    return tag.replace(/\s*\/?>$/, (close) => ` ${attr}="${value}"${close}`);
+}
+//# sourceMappingURL=get-embed-code.js.map

package/dist/tools/get-embed-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-embed-code.js","sourceRoot":"","sources":["../../src/tools/get-embed-code.ts"],"names":[],"mappings":"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"}

package/dist/tools/insights/analyze-share-links.d.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+import { type McpToolError } from '../../conventions/errors.js';
+export declare const ANALYZE_SHARE_LINKS_DESCRIPTION: string;
+export declare const DEFAULT_TOP_N = 10;
+export declare const MAX_TOP_N = 50;
+export declare const ENUMERATOR_HARD_CAP = 5000;
+/**
+ * `date_from` / `date_to` are inclusive ISO-8601 date or datetime strings.
+ * If only a date is supplied (e.g. `2026-04-14`), it is interpreted as
+ * the start (00:00:00Z) for `date_from` or the end (23:59:59.999Z) for
+ * `date_to`. Both bounds are optional — omit to leave that side
+ * unbounded.
+ */
+export declare const AnalyzeShareLinksInputSchema: z.ZodObject<{
+    date_from: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    date_to: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    collection_id: z.ZodOptional<z.ZodString>;
+    created_by_user_id: z.ZodOptional<z.ZodString>;
+    top_n: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    top_n: number;
+    collection_id?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    created_by_user_id?: string | undefined;
+}, {
+    collection_id?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+    created_by_user_id?: string | undefined;
+    top_n?: number | undefined;
+}>;
+export type AnalyzeShareLinksInput = z.input<typeof AnalyzeShareLinksInputSchema>;
+export type AnalyzeShareLinksInputResolved = z.output<typeof AnalyzeShareLinksInputSchema>;
+export type ShareLinkStatus = 'active' | 'expired' | 'revoked';
+export interface ShareLinkRow {
+    id: string;
+    title: string | null;
+    share_url: string | null;
+    view_count: number;
+    created_at: string | null;
+    expires_at: string | null;
+    status: ShareLinkStatus;
+    /** Numeric/string id of the creating user, if upstream returned it. */
+    created_by_user_id: string | null;
+    /** Asset IDs covered by this share link (for collection-scope filtering). */
+    asset_ids: string[];
+    /** Collection id when the row is a collection-share, else null. */
+    collection_id: string | null;
+}
+/**
+ * The analyzer pulls the entire workspace share-link list through this
+ * narrow surface. Implementations may paginate internally and SHOULD cap
+ * at {@link ENUMERATOR_HARD_CAP} items, surfacing `truncated: true` so
+ * the report can flag that the dataset was clipped.
+ *
+ * Errors are returned as typed `McpToolError` rather than thrown — the
+ * analyzer surfaces them through the canonical error taxonomy.
+ */
+export interface ShareLinkEnumerator {
+    enumerate(): Promise<{
+        ok: true;
+        rows: ShareLinkRow[];
+        truncated: boolean;
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+export interface ShareLinkTopEntry {
+    id: string;
+    title: string | null;
+    share_url: string | null;
+    view_count: number;
+    status: ShareLinkStatus;
+    created_at: string | null;
+    expires_at: string | null;
+}
+export interface ShareLinkTimeSeriesPoint {
+    /** ISO date (YYYY-MM-DD) bucket. */
+    date: string;
+    /** Number of share links created on this date. */
+    links_created: number;
+}
+export interface ShareLinkCohortEntry {
+    /** Cohort key (user id, collection id, etc.). */
+    key: string;
+    /** Number of share links attributed to this cohort. */
+    link_count: number;
+    /** Sum of view counts across links in this cohort. */
+    view_count: number;
+}
+export interface ShareLinkAnalyticsReport {
+    /** Inputs as resolved (after defaults / filters applied). */
+    filters: {
+        date_from: string | null;
+        date_to: string | null;
+        collection_id: string | null;
+        created_by_user_id: string | null;
+        top_n: number;
+    };
+    totals: {
+        /** Number of share links matching the filters. */
+        link_count: number;
+        /** Total views across all matching links. */
+        total_views: number;
+        /** Mean views per link (null when link_count === 0). */
+        mean_views: number | null;
+        /** Median views per link (null when link_count === 0). */
+        median_views: number | null;
+    };
+    status_distribution: {
+        active: number;
+        expired: number;
+        revoked: number;
+    };
+    top_links: ShareLinkTopEntry[];
+    /**
+     * Daily creation cadence over the matching range. Sorted ascending by
+     * `date`. Per-day view counts are not modeled — see file header.
+     */
+    time_series: {
+        links_created_per_day: ShareLinkTimeSeriesPoint[];
+        /** Daily views are not exposed by upstream; null is intentional. */
+        views_per_day: null;
+    };
+    cohorts: {
+        by_creator: ShareLinkCohortEntry[];
+        /** Only populated when `collection_id` filter is set; else empty array. */
+        by_collection: ShareLinkCohortEntry[];
+    };
+    /** True when the enumerator clipped at {@link ENUMERATOR_HARD_CAP}. */
+    truncated: boolean;
+    truncation_reason?: string;
+}
+export interface AnalyzeShareLinksDeps {
+    enumerator: ShareLinkEnumerator;
+}
+export type AnalyzeShareLinksOutcome = {
+    ok: true;
+    report: ShareLinkAnalyticsReport;
+} | {
+    ok: false;
+    error: McpToolError;
+};
+export declare class AnalyzeShareLinksTool {
+    private readonly deps;
+    readonly name = "analyze_share_links";
+    readonly description: string;
+    constructor(deps: AnalyzeShareLinksDeps);
+    run(rawInput?: AnalyzeShareLinksInput): Promise<AnalyzeShareLinksOutcome>;
+}
+export declare function buildAnalyzeShareLinksTool(deps: AnalyzeShareLinksDeps): AnalyzeShareLinksTool;
+/**
+ * Build the analytics report from a flat list of rows. Pure function,
+ * exported for direct test access.
+ */
+export declare function buildReport(rows: ReadonlyArray<ShareLinkRow>, enumeratorTruncated: boolean, input: AnalyzeShareLinksInputResolved): ShareLinkAnalyticsReport;
+//# sourceMappingURL=analyze-share-links.d.ts.map

package/dist/tools/insights/analyze-share-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-share-links.d.ts","sourceRoot":"","sources":["../../../src/tools/insights/analyze-share-links.ts"],"names":[],"mappings":"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"}