@lightsage/mcp 0.4.16 → 0.4.18

package/src/models/publiccitationsummarygroup.ts

@@ -0,0 +1,54 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 5da2b8693555
+ */
+
+import * as z from "zod";
+
+export type PublicCitationSummaryGroup = {
+  key: string;
+  url?: string | null | undefined;
+  title?: string | null | undefined;
+  is_company_link: boolean;
+  citation_count: number;
+  previous_citation_count: number;
+  change?: number | null | undefined;
+  citations_per_run?: number | null | undefined;
+  previous_citations_per_run?: number | null | undefined;
+  per_run_change?: number | null | undefined;
+  prompt_count: number;
+  url_count: number;
+};
+
+export const PublicCitationSummaryGroup$zodSchema: z.ZodType<
+  PublicCitationSummaryGroup
+> = z.object({
+  change: z.number().nullable().optional().describe(
+    "Relative change in citations; 0.25 means 25% higher.",
+  ),
+  citation_count: z.int().describe("Citations in the period."),
+  citations_per_run: z.number().nullable().optional(),
+  is_company_link: z.boolean().describe(
+    "Whether the group includes an owned company domain.",
+  ),
+  key: z.string().describe(
+    "The group: a URL prefix (domain and first path segment, such as `example.com/blog`), a normalized URL, a domain, or a day (YYYY-MM-DD).",
+  ),
+  per_run_change: z.number().nullable().optional().describe(
+    "Relative change in citations per run.",
+  ),
+  previous_citation_count: z.int().describe(
+    "Citations in the previous period. For `day` groups, the matching day of the previous period.",
+  ),
+  previous_citations_per_run: z.number().nullable().optional(),
+  prompt_count: z.int().describe(
+    "Distinct active prompts that cited the group in the period.",
+  ),
+  title: z.string().nullable().optional().describe(
+    "Page title, for `url` groups.",
+  ),
+  url: z.string().nullable().optional().describe(
+    "Most frequently observed variant of the URL, for `url` groups.",
+  ),
+  url_count: z.int().describe("Distinct URLs in the group in the period."),
+});

package/src/models/publiccitationsummaryresponse.ts

@@ -0,0 +1,110 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 0db6ff4a9411
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+import {
+  PublicCitationSummaryGroup,
+  PublicCitationSummaryGroup$zodSchema,
+} from "./publiccitationsummarygroup.js";
+import {
+  PublicCitationSummaryTotals,
+  PublicCitationSummaryTotals$zodSchema,
+} from "./publiccitationsummarytotals.js";
+import { PublicCoverage, PublicCoverage$zodSchema } from "./publiccoverage.js";
+import {
+  PublicResolvedPeriod,
+  PublicResolvedPeriod$zodSchema,
+} from "./publicresolvedperiod.js";
+
+export const GroupBy = {
+  UrlPrefix: "url_prefix",
+  Url: "url",
+  Domain: "domain",
+  Day: "day",
+} as const;
+export type GroupBy = ClosedEnum<typeof GroupBy>;
+
+export const GroupBy$zodSchema = z.enum([
+  "url_prefix",
+  "url",
+  "domain",
+  "day",
+]);
+
+export const PublicCitationSummaryResponseSourceType = {
+  All: "all",
+  Owned: "owned",
+  External: "external",
+} as const;
+export type PublicCitationSummaryResponseSourceType = ClosedEnum<
+  typeof PublicCitationSummaryResponseSourceType
+>;
+
+export const PublicCitationSummaryResponseSourceType$zodSchema = z.enum([
+  "all",
+  "owned",
+  "external",
+]);
+
+/**
+ * The number to lead with: citation counts when the periods are comparable, otherwise citations per run.
+ */
+export const PublicCitationSummaryResponseHeadlineMetric = {
+  CitationCount: "citation_count",
+  CitationsPerRun: "citations_per_run",
+} as const;
+/**
+ * The number to lead with: citation counts when the periods are comparable, otherwise citations per run.
+ */
+export type PublicCitationSummaryResponseHeadlineMetric = ClosedEnum<
+  typeof PublicCitationSummaryResponseHeadlineMetric
+>;
+
+export const PublicCitationSummaryResponseHeadlineMetric$zodSchema = z.enum([
+  "citation_count",
+  "citations_per_run",
+]).describe(
+  "The number to lead with: citation counts when the periods are comparable, otherwise citations per run.",
+);
+
+export type PublicCitationSummaryResponse = {
+  period: PublicResolvedPeriod;
+  group_by: GroupBy;
+  url_prefix?: string | null | undefined;
+  source_type: PublicCitationSummaryResponseSourceType;
+  platform?: string | null | undefined;
+  headline_metric: PublicCitationSummaryResponseHeadlineMetric;
+  totals: PublicCitationSummaryTotals;
+  has_data: boolean;
+  group_count: number;
+  count: number;
+  groups?: Array<PublicCitationSummaryGroup> | undefined;
+  coverage: PublicCoverage;
+};
+
+export const PublicCitationSummaryResponse$zodSchema: z.ZodType<
+  PublicCitationSummaryResponse
+> = z.object({
+  count: z.int().describe("Groups returned."),
+  coverage: PublicCoverage$zodSchema,
+  group_by: GroupBy$zodSchema,
+  group_count: z.int().describe("Groups matching the filters, before `limit`."),
+  groups: z.array(PublicCitationSummaryGroup$zodSchema).optional().describe(
+    "Groups by citation count, most first; `day` groups are in date order.",
+  ),
+  has_data: z.boolean(),
+  headline_metric: PublicCitationSummaryResponseHeadlineMetric$zodSchema
+    .describe(
+      "The number to lead with: citation counts when the periods are comparable, otherwise citations per run.",
+    ),
+  period: PublicResolvedPeriod$zodSchema,
+  platform: z.string().nullable().optional(),
+  source_type: PublicCitationSummaryResponseSourceType$zodSchema,
+  totals: PublicCitationSummaryTotals$zodSchema,
+  url_prefix: z.string().nullable().optional().describe(
+    "URL prefix filter applied, if any.",
+  ),
+});

package/src/models/publiccitationsummarytotals.ts

@@ -0,0 +1,38 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 10a1503650d5
+ */
+
+import * as z from "zod";
+
+export type PublicCitationSummaryTotals = {
+  citation_count: number;
+  previous_citation_count: number;
+  change?: number | null | undefined;
+  run_count: number;
+  previous_run_count: number;
+  citations_per_run?: number | null | undefined;
+  previous_citations_per_run?: number | null | undefined;
+  per_run_change?: number | null | undefined;
+  url_count: number;
+};
+
+export const PublicCitationSummaryTotals$zodSchema: z.ZodType<
+  PublicCitationSummaryTotals
+> = z.object({
+  change: z.number().nullable().optional().describe(
+    "Relative change in citations; 0.25 means 25% higher.",
+  ),
+  citation_count: z.int(),
+  citations_per_run: z.number().nullable().optional(),
+  per_run_change: z.number().nullable().optional().describe(
+    "Relative change in citations per run.",
+  ),
+  previous_citation_count: z.int(),
+  previous_citations_per_run: z.number().nullable().optional(),
+  previous_run_count: z.int(),
+  run_count: z.int().describe(
+    "Successful runs of active prompts in the period, after the platform filter.",
+  ),
+  url_count: z.int().describe("Distinct cited URLs in the period."),
+});

package/src/models/publiccoverage.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 4193289784d8
+ */
+
+import * as z from "zod";
+import {
+  PublicCoverageDay,
+  PublicCoverageDay$zodSchema,
+} from "./publiccoverageday.js";
+import {
+  PublicPeriodCoverage,
+  PublicPeriodCoverage$zodSchema,
+} from "./publicperiodcoverage.js";
+
+export type PublicCoverage = {
+  comparable: boolean;
+  notes?: Array<string> | undefined;
+  current: PublicPeriodCoverage;
+  previous: PublicPeriodCoverage;
+  days?: Array<PublicCoverageDay> | undefined;
+};
+
+export const PublicCoverage$zodSchema: z.ZodType<PublicCoverage> = z.object({
+  comparable: z.boolean().describe(
+    "Whether totals can be compared between the two periods. False when either period has a missing or short day or runs per day differ by more than 20%; compare per-run rates instead.",
+  ),
+  current: PublicPeriodCoverage$zodSchema,
+  days: z.array(PublicCoverageDay$zodSchema).optional(),
+  notes: z.array(z.string()).optional().describe(
+    "Why the periods are not comparable, in plain sentences.",
+  ),
+  previous: PublicPeriodCoverage$zodSchema,
+});

package/src/models/publiccoverageday.ts

@@ -0,0 +1,68 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 934b3f835415
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const Period = {
+  Current: "current",
+  Previous: "previous",
+} as const;
+export type Period = ClosedEnum<typeof Period>;
+
+export const Period$zodSchema = z.enum([
+  "current",
+  "previous",
+]);
+
+/**
+ * `missing`: no runs on a day that expected some. `short`: under half the expected runs. `in_progress`: today, before its runs finished.
+ */
+export const PublicCoverageDayStatus = {
+  Ok: "ok",
+  Short: "short",
+  Missing: "missing",
+  InProgress: "in_progress",
+  NotExpected: "not_expected",
+} as const;
+/**
+ * `missing`: no runs on a day that expected some. `short`: under half the expected runs. `in_progress`: today, before its runs finished.
+ */
+export type PublicCoverageDayStatus = ClosedEnum<
+  typeof PublicCoverageDayStatus
+>;
+
+export const PublicCoverageDayStatus$zodSchema = z.enum([
+  "ok",
+  "short",
+  "missing",
+  "in_progress",
+  "not_expected",
+]).describe(
+  "`missing`: no runs on a day that expected some. `short`: under half the expected runs. `in_progress`: today, before its runs finished.",
+);
+
+export type PublicCoverageDay = {
+  date: string;
+  period: Period;
+  runs: number;
+  expected_runs: number;
+  status: PublicCoverageDayStatus;
+};
+
+export const PublicCoverageDay$zodSchema: z.ZodType<PublicCoverageDay> = z
+  .object({
+    date: z.string(),
+    expected_runs: z.int().describe(
+      "Median daily runs over the 7 days before; 0 when no daily runs are expected.",
+    ),
+    period: Period$zodSchema,
+    runs: z.int().describe(
+      "Successful prompt runs of active prompts that day.",
+    ),
+    status: PublicCoverageDayStatus$zodSchema.describe(
+      "`missing`: no runs on a day that expected some. `short`: under half the expected runs. `in_progress`: today, before its runs finished.",
+    ),
+  });

package/src/models/publiccurrentvisibilityresponse.ts

@@ -5,6 +5,16 @@
 
 import * as z from "zod";
 import { PublicCompany, PublicCompany$zodSchema } from "./publiccompany.js";
+import { PublicCoverage, PublicCoverage$zodSchema } from "./publiccoverage.js";
+import {
+  PublicPreviousVisibility,
+  PublicPreviousVisibility$zodSchema,
+} from "./publicpreviousvisibility.js";
+import { PublicRates, PublicRates$zodSchema } from "./publicrates.js";
+import {
+  PublicResolvedPeriod,
+  PublicResolvedPeriod$zodSchema,
+} from "./publicresolvedperiod.js";
 
 export type PublicCurrentVisibilityResponse = {
   company: PublicCompany;
@@ -21,6 +31,10 @@ export type PublicCurrentVisibilityResponse = {
   end_date: string;
   active_prompts_only?: boolean | undefined;
   has_data: boolean;
+  period?: PublicResolvedPeriod | null | undefined;
+  previous?: PublicPreviousVisibility | null | undefined;
+  coverage?: PublicCoverage | null | undefined;
+  rates?: PublicRates | null | undefined;
 };
 
 export const PublicCurrentVisibilityResponse$zodSchema: z.ZodType<
@@ -32,11 +46,23 @@ export const PublicCurrentVisibilityResponse$zodSchema: z.ZodType<
   ),
   average_position_rank: z.int().nullable().optional(),
   company: PublicCompany$zodSchema,
+  coverage: PublicCoverage$zodSchema.nullable().optional().describe(
+    "Runs per day against expected runs for both periods. Check `comparable` before comparing totals.",
+  ),
   date: z.string().nullable().optional().describe(
     "Latest prompt-run date in the range.",
   ),
   end_date: z.string(),
   has_data: z.boolean(),
+  period: PublicResolvedPeriod$zodSchema.nullable().optional().describe(
+    "The resolved period and the previous period it is compared with.",
+  ),
+  previous: PublicPreviousVisibility$zodSchema.nullable().optional().describe(
+    "The same metrics for the previous period.",
+  ),
+  rates: PublicRates$zodSchema.nullable().optional().describe(
+    "Runs, owned citations, and per-run rates for both periods. Lead with `headline_metric`.",
+  ),
   recommendation_score: z.number().nullable().optional().describe(
     "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings › Navigation.",
   ),

package/src/models/publicperiodcoverage.ts

@@ -0,0 +1,33 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 826ee3c7ea7a
+ */
+
+import * as z from "zod";
+
+export type PublicPeriodCoverage = {
+  start_date: string;
+  end_date: string;
+  runs: number;
+  expected_runs: number;
+  complete_days: number;
+  runs_per_day?: number | null | undefined;
+  missing_days?: Array<string> | undefined;
+  short_days?: Array<string> | undefined;
+};
+
+export const PublicPeriodCoverage$zodSchema: z.ZodType<PublicPeriodCoverage> = z
+  .object({
+    complete_days: z.int().describe(
+      "Days in the period other than today in progress.",
+    ),
+    end_date: z.string(),
+    expected_runs: z.int(),
+    missing_days: z.array(z.string()).optional(),
+    runs: z.int(),
+    runs_per_day: z.number().nullable().optional().describe(
+      "Runs per complete day.",
+    ),
+    short_days: z.array(z.string()).optional(),
+    start_date: z.string(),
+  });

package/src/models/publicperiodrates.ts

@@ -0,0 +1,29 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: e7a509001b7d
+ */
+
+import * as z from "zod";
+
+export type PublicPeriodRates = {
+  runs: number;
+  owned_citations: number;
+  owned_citations_per_run?: number | null | undefined;
+  brand_mention_runs: number;
+  mention_rate?: number | null | undefined;
+};
+
+export const PublicPeriodRates$zodSchema: z.ZodType<PublicPeriodRates> = z
+  .object({
+    brand_mention_runs: z.int().describe(
+      "Runs that mention the primary company.",
+    ),
+    mention_rate: z.number().nullable().optional().describe(
+      "Share of runs that mention the primary company, from 0 to 1.",
+    ),
+    owned_citations: z.int().describe(
+      "Citations of the organization's own domains.",
+    ),
+    owned_citations_per_run: z.number().nullable().optional(),
+    runs: z.int(),
+  });

package/src/models/publicpreviousvisibility.ts

@@ -0,0 +1,30 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: b65281016f32
+ */
+
+import * as z from "zod";
+
+export type PublicPreviousVisibility = {
+  recommendation_score?: number | null | undefined;
+  visibility_score?: number | null | undefined;
+  share_of_voice?: number | null | undefined;
+  average_position?: number | null | undefined;
+  has_data?: boolean | undefined;
+};
+
+export const PublicPreviousVisibility$zodSchema: z.ZodType<
+  PublicPreviousVisibility
+> = z.object({
+  average_position: z.number().nullable().optional(),
+  has_data: z.boolean().default(false),
+  recommendation_score: z.number().nullable().optional().describe(
+    "Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings › Navigation.",
+  ),
+  share_of_voice: z.number().nullable().optional().describe(
+    "The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`.",
+  ),
+  visibility_score: z.number().nullable().optional().describe(
+    "Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded.",
+  ),
+});

package/src/models/publicpromptvisibilityreportresponse.ts

@@ -5,6 +5,7 @@
 
 import * as z from "zod";
 import { PublicCompany, PublicCompany$zodSchema } from "./publiccompany.js";
+import { PublicCoverage, PublicCoverage$zodSchema } from "./publiccoverage.js";
 import {
   PublicPromptVisibilityDateRange,
   PublicPromptVisibilityDateRange$zodSchema,
@@ -13,6 +14,11 @@ import {
   PublicPromptVisibilitySummary,
   PublicPromptVisibilitySummary$zodSchema,
 } from "./publicpromptvisibilitysummary.js";
+import { PublicRates, PublicRates$zodSchema } from "./publicrates.js";
+import {
+  PublicResolvedPeriod,
+  PublicResolvedPeriod$zodSchema,
+} from "./publicresolvedperiod.js";
 import {
   PublicTopicVisibilityRow,
   PublicTopicVisibilityRow$zodSchema,
@@ -24,14 +30,26 @@ export type PublicPromptVisibilityReportResponse = {
   has_data: boolean;
   summary: PublicPromptVisibilitySummary;
   topics?: Array<PublicTopicVisibilityRow> | undefined;
+  period?: PublicResolvedPeriod | null | undefined;
+  coverage?: PublicCoverage | null | undefined;
+  rates?: PublicRates | null | undefined;
 };
 
 export const PublicPromptVisibilityReportResponse$zodSchema: z.ZodType<
   PublicPromptVisibilityReportResponse
 > = z.object({
   company: PublicCompany$zodSchema,
+  coverage: PublicCoverage$zodSchema.nullable().optional().describe(
+    "Runs per day against expected runs for both periods. Check `comparable` before comparing totals.",
+  ),
   date_range: PublicPromptVisibilityDateRange$zodSchema,
   has_data: z.boolean(),
+  period: PublicResolvedPeriod$zodSchema.nullable().optional().describe(
+    "The resolved period and the previous period it is compared with.",
+  ),
+  rates: PublicRates$zodSchema.nullable().optional().describe(
+    "Runs, owned citations, and per-run rates for both periods. Lead with `headline_metric`.",
+  ),
   summary: PublicPromptVisibilitySummary$zodSchema,
   topics: z.array(PublicTopicVisibilityRow$zodSchema).optional(),
 });

package/src/models/publicratechanges.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 7e8926781b3d
+ */
+
+import * as z from "zod";
+
+export type PublicRateChanges = {
+  owned_citations?: number | null | undefined;
+  owned_citations_per_run?: number | null | undefined;
+  mention_rate?: number | null | undefined;
+};
+
+export const PublicRateChanges$zodSchema: z.ZodType<PublicRateChanges> = z
+  .object({
+    mention_rate: z.number().nullable().optional().describe(
+      "Relative change from the previous period.",
+    ),
+    owned_citations: z.number().nullable().optional().describe(
+      "Relative change from the previous period; 0.25 means 25% higher.",
+    ),
+    owned_citations_per_run: z.number().nullable().optional().describe(
+      "Relative change from the previous period.",
+    ),
+  });

package/src/models/publicrates.ts

@@ -0,0 +1,52 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 9b8379be34f2
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+import {
+  PublicPeriodRates,
+  PublicPeriodRates$zodSchema,
+} from "./publicperiodrates.js";
+import {
+  PublicRateChanges,
+  PublicRateChanges$zodSchema,
+} from "./publicratechanges.js";
+
+/**
+ * The number to lead with: owned citations when the periods are comparable, otherwise owned citations per run.
+ */
+export const PublicRatesHeadlineMetric = {
+  OwnedCitations: "owned_citations",
+  OwnedCitationsPerRun: "owned_citations_per_run",
+} as const;
+/**
+ * The number to lead with: owned citations when the periods are comparable, otherwise owned citations per run.
+ */
+export type PublicRatesHeadlineMetric = ClosedEnum<
+  typeof PublicRatesHeadlineMetric
+>;
+
+export const PublicRatesHeadlineMetric$zodSchema = z.enum([
+  "owned_citations",
+  "owned_citations_per_run",
+]).describe(
+  "The number to lead with: owned citations when the periods are comparable, otherwise owned citations per run.",
+);
+
+export type PublicRates = {
+  headline_metric: PublicRatesHeadlineMetric;
+  current: PublicPeriodRates;
+  previous: PublicPeriodRates;
+  change: PublicRateChanges;
+};
+
+export const PublicRates$zodSchema: z.ZodType<PublicRates> = z.object({
+  change: PublicRateChanges$zodSchema,
+  current: PublicPeriodRates$zodSchema,
+  headline_metric: PublicRatesHeadlineMetric$zodSchema.describe(
+    "The number to lead with: owned citations when the periods are comparable, otherwise owned citations per run.",
+  ),
+  previous: PublicPeriodRates$zodSchema,
+});

package/src/models/publicresolvedperiod.ts

@@ -0,0 +1,41 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: eeb8e6b4cc74
+ */
+
+import * as z from "zod";
+
+export type PublicResolvedPeriod = {
+  name?: string | null | undefined;
+  start_date: string;
+  end_date: string;
+  days: number;
+  previous_start_date: string;
+  previous_end_date: string;
+  previous_days: number;
+  partial: boolean;
+  timezone?: "UTC" | undefined;
+};
+
+export const PublicResolvedPeriod$zodSchema: z.ZodType<PublicResolvedPeriod> = z
+  .object({
+    days: z.int().describe("Days in the period, counting both ends."),
+    end_date: z.string().describe("Last day of the period (UTC), inclusive."),
+    name: z.string().nullable().optional().describe(
+      "The `period` requested, or null when the range came from `start_date` and `end_date`.",
+    ),
+    partial: z.boolean().describe(
+      "Whether the period includes today, so its last day is still in progress.",
+    ),
+    previous_days: z.int().describe("Days in the previous period."),
+    previous_end_date: z.string().describe(
+      "Last day of the previous period. While a calendar week, month, or quarter is in progress, the previous one is cut to the same number of days.",
+    ),
+    previous_start_date: z.string().describe(
+      "First day of the previous period it is compared with.",
+    ),
+    start_date: z.string().describe(
+      "First day of the period (UTC), inclusive.",
+    ),
+    timezone: z.literal("UTC").default("UTC"),
+  });