@elmohq/sdk 0.0.0-stage → 0.1.0

package/src/types/reports.ts

@@ -0,0 +1,266 @@
+import type { ConflictError, PaymentRequiredError } from './shared/conflict-error';
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { Limit } from './shared/limit';
+import type { MentionsSummary } from './shared/mention-entry';
+import type { NotFoundError } from './shared/not-found-error';
+import type { Page } from './shared/page';
+import type { ValidationError } from './shared/validation-error';
+
+export type ReportSummary = {
+  /** Other names counted as brand mentions */
+  brandAliases: Array<string>;
+  /** Brand name analyzed */
+  brandName: string;
+  /** Brand website URL */
+  brandWebsite: string;
+  /** Timestamp when the report completed */
+  completedAt: Date | null;
+  /** Timestamp when the report was created */
+  createdAt: Date;
+  /** Unique identifier for the report */
+  id: string;
+  /** Current report status */
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+};
+
+/**
+ * Per-prompt snapshot of raw mention data from a report. Consumers compute SoV and other derived
+ * metrics.
+ */
+export type ReportPromptSnapshot = {
+  mentions: MentionsSummary;
+  /** The prompt text that was evaluated */
+  promptValue: string;
+  /** Number of evaluation runs for this prompt */
+  totalRuns: number;
+};
+
+export type ListReportsErrors = {
+  /** Authentication required */
+  401: UnauthorizedError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type ListReportsResponses = {
+  /** Paginated list of reports */
+  200: {
+    /** The items on this page. Read this rather than the named key below. */
+    data: Array<ReportSummary>;
+    pagination: {
+      limit: number;
+      page: number;
+      total: number;
+      totalPages: number;
+    };
+    /**
+     * Deprecated: read `data` instead. Kept while the one known consumer migrates, and removed in a
+     * future release.
+     *
+     * @deprecated
+     */
+    reports: Array<ReportSummary>;
+  };
+};
+
+export type ListReportsResponse = ListReportsResponses[keyof ListReportsResponses];
+
+export type CreateReportErrors = {
+  /** Invalid request data */
+  400: ValidationError;
+  /** Authentication required */
+  401: UnauthorizedError;
+  /** The organization has no active subscription. Cloud deployments only. */
+  402: PaymentRequiredError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Resource already exists */
+  409: ConflictError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type CreateReportResponses = {
+  /** Report created and queued for generation */
+  201: {
+    brandAliases: Array<string>;
+    brandName: string;
+    brandWebsite: string;
+    createdAt: Date;
+    /** Unique identifier for the created report */
+    reportId: string;
+    /** Initial report status */
+    status: 'pending';
+  };
+};
+
+export type CreateReportResponse = CreateReportResponses[keyof CreateReportResponses];
+
+export type GetReportErrors = {
+  /** Invalid request data */
+  400: ValidationError;
+  /** Authentication required */
+  401: UnauthorizedError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Resource not found */
+  404: NotFoundError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type GetReportResponses = {
+  /**
+   * Report status and data. When status is 'completed', includes per-prompt snapshot data with raw
+   * mention counts.
+   */
+  200: {
+    brandAliases: Array<string>;
+    brandName: string;
+    brandWebsite: string;
+    completedAt: Date | null;
+    createdAt: Date;
+    /** Generation progress percentage (0-100). Available while processing. */
+    progress?: number;
+    /** Per-prompt snapshot data. Only present when status is 'completed'. */
+    prompts?: Array<ReportPromptSnapshot>;
+    reportId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /**
+     * Derived stats (SoV, visibility, etc.). Format may change between versions. Only present when
+     * status is 'completed'.
+     */
+    unstable?: {
+      /** Per-competitor SoV breakdown, sorted by SoV descending */
+      competitors?: Array<{
+        /** Competitor name */
+        name: string;
+        /** Number of individual prompt runs where this competitor was mentioned */
+        promptRunsWithMentions: number;
+        /** Number of prompts where this competitor was mentioned in at least one run */
+        promptsWithMentions: number;
+        /**
+         * Share of voice (0-1): this competitor's mentions / total mentions (brand + all
+         * competitors)
+         *
+         * @minimum 0
+         * @maximum 1
+         */
+        sov: number;
+        /**
+         * Visibility (0-1): prompt runs mentioning this competitor / total prompt runs
+         *
+         * @minimum 0
+         * @maximum 1
+         */
+        visibility: number;
+      }>;
+      /** Number of individual prompt runs where the brand was mentioned */
+      promptRunsWithBrandMentions?: number;
+      /** Number of prompts where the brand was mentioned in at least one prompt run */
+      promptsWithBrandMentions?: number;
+      /**
+       * Overall share of voice (0-1): brand_mentions / (brand_mentions + competitor_mentions). Null
+       * when no mentions at all.
+       *
+       * @minimum 0
+       * @maximum 1
+       */
+      sov?: number | null;
+      /**
+       * Total number of prompt runs across all prompts (each prompt is executed multiple times
+       * across different AI engines)
+       */
+      totalPromptRuns?: number;
+      /** Total number of prompts evaluated */
+      totalPrompts?: number;
+      /**
+       * Brand visibility (0-1): brand_mentions / total_prompt_runs (how often the brand appears at
+       * all across all prompt runs)
+       *
+       * @minimum 0
+       * @maximum 1
+       */
+      visibility?: number;
+    };
+  };
+};
+
+export type GetReportResponse = GetReportResponses[keyof GetReportResponses];
+
+export type ListReportsParams = {
+  /**
+   * Page number, 1-based.
+   *
+   * @default 1
+   * @minimum 1
+   */
+  page?: Page;
+  /**
+   * Items per page. Values above the maximum are clamped, not rejected.
+   *
+   * @default 20
+   * @minimum 1
+   * @maximum 100
+   */
+  limit?: Limit;
+};
+
+export type CreateReportParams = {
+  /**
+   * The brand name to analyze
+   *
+   * @minLength 1
+   */
+  brandName: string;
+  /**
+   * Other names the brand goes by (spellings, abbreviations, product names). A mention of any of
+   * them counts as a brand mention.
+   *
+   * @maxItems 10
+   */
+  brandAliases?: Array<string>;
+  /**
+   * The brand's website — a domain (nike.com) or a full URL. A URL with a path (e.g.
+   * https://www.nike.com/golf) scopes the analysis to that page; mentions are tracked against its
+   * domain either way.
+   *
+   * @minLength 1
+   */
+  brandWebsite: string;
+  /** Optional list of custom prompts to include in the report */
+  manualPrompts?: Array<string>;
+};
+
+export type GetReportParams = {
+  /**
+   * Number of top competitor entities to return in each prompt's mentionsTopK
+   *
+   * @default 5
+   * @minimum 1
+   * @maximum 50
+   */
+  kMentions?: number;
+};

package/src/types/runs.ts

@@ -0,0 +1,131 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { Limit } from './shared/limit';
+import type { ModelFilter, WindowEnd, WindowStart } from './shared/model-filter';
+import type { NotFoundError } from './shared/not-found-error';
+import type { Page } from './shared/page';
+import type { Pagination } from './shared/pagination';
+import type { ValidationError } from './shared/validation-error';
+
+/** A single model answer, without its text. Fetch `prompts.runs.get()` for the answer itself. */
+export type RunSummary = {
+  brandId: string;
+  brandMentioned: boolean;
+  citationCount: number;
+  competitorsMentioned: Array<string>;
+  createdAt: Date;
+  id: string;
+  model: string;
+  promptId: string;
+  /** How the answer was obtained. Informational; not a stable enum. */
+  provider: string | null;
+  /** Searches the engine ran, where it exposes them. */
+  webQueries: Array<string>;
+  /** Whether the engine answered with its own web search on. */
+  webSearchEnabled: boolean;
+};
+
+export type RunCitation = {
+  /** Position within the answer's citation list. */
+  citationIndex: number;
+  domain: string;
+  title: string | null;
+  url: string;
+};
+
+/** One model answer with its normalized text and citations. */
+export type Run = RunSummary & {
+  answer: {
+    /**
+     * The answer, normalized out of the provider's response. Null when nothing could be extracted.
+     */
+    text: string | null;
+  };
+  citations: Array<RunCitation>;
+};
+
+export type RunList = {
+  data: Array<RunSummary>;
+  pagination: Pagination;
+};
+
+export type ListPromptRunsErrors = {
+  /** Invalid request data */
+  400: ValidationError;
+  /** Authentication required */
+  401: UnauthorizedError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Resource not found */
+  404: NotFoundError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type ListPromptRunsResponses = {
+  /** List runs for a prompt */
+  200: RunList;
+};
+
+export type GetRunErrors = {
+  /** Invalid request data */
+  400: ValidationError;
+  /** Authentication required */
+  401: UnauthorizedError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Resource not found */
+  404: NotFoundError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type GetRunResponses = {
+  /** Get a run */
+  200: Run;
+};
+
+export type ListPromptRunsParams = {
+  /**
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
+   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
+   * local calendar day there.
+   */
+  start: WindowStart;
+  /**
+   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
+   * exactly `end` is outside it.
+   */
+  end: WindowEnd;
+  /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */
+  model?: ModelFilter;
+  /**
+   * Page number, 1-based.
+   *
+   * @default 1
+   * @minimum 1
+   */
+  page?: Page;
+  /**
+   * Items per page. Values above the maximum are clamped, not rejected.
+   *
+   * @default 20
+   * @minimum 1
+   * @maximum 100
+   */
+  limit?: Limit;
+};

package/src/types/shared/brand-id-path.ts

@@ -0,0 +1,2 @@
+/** Brand identifier. */
+export type BrandIdPath = string;

package/src/types/shared/conflict-error.ts

@@ -0,0 +1,7 @@
+import type { Error } from './error';
+
+/** Resource already exists */
+export type ConflictError = Error;
+
+/** The organization has no active subscription. Cloud deployments only. */
+export type PaymentRequiredError = Error;

package/src/types/shared/error.ts

@@ -0,0 +1,29 @@
+export type Error = {
+  /**
+   * Stable machine-readable code. Deliberately not an enum: new values are added without a version
+   * bump, so treat an unrecognized one as its HTTP status implies. Currently: `unauthorized`,
+   * `insufficient_scope`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`,
+   * `method_not_allowed`, `read_only`, `no_active_plan`, `brand_limit`, `prompt_limit`,
+   * `model_not_in_plan`, `model_picks_exceeded`, `premium_not_in_plan`, `premium_pool_exhausted`,
+   * `cadence_faster_than_plan`, `internal_error`.
+   */
+  code?: string;
+  /** Error type */
+  error: string;
+  /** Detailed error message */
+  message?: string;
+};
+
+/** Authentication required */
+export type UnauthorizedError = Error;
+
+export type InternalServerError = Error;
+
+/**
+ * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+ * read-only (demo) mode.
+ */
+export type ForbiddenError = Error;
+
+/** Per-key rate limit exceeded. */
+export type RateLimitError = Error;

package/src/types/shared/limit.ts

@@ -0,0 +1,8 @@
+/**
+ * Items per page. Values above the maximum are clamped, not rejected.
+ *
+ * @default 20
+ * @minimum 1
+ * @maximum 100
+ */
+export type Limit = number;

package/src/types/shared/mention-entry.ts

@@ -0,0 +1,21 @@
+/** Aggregated mention counts for a prompt across its evaluation runs. */
+export type MentionsSummary = {
+  /** Number of runs where the brand was mentioned */
+  brandMentionsTotal: number;
+  /**
+   * Total count of individual competitor mentions across all runs (a single run mentioning 3
+   * competitors counts as 3)
+   */
+  competitorMentionsTotal: number;
+  /** Top-K competitor entities ranked by mention count */
+  mentionsTopK: Array<MentionEntry>;
+  /** Total brand + competitor mentions across all runs */
+  mentionsTotal: number;
+};
+
+export type MentionEntry = {
+  /** Number of runs where this entity was mentioned */
+  count: number;
+  /** Competitor entity name */
+  entity: string;
+};

package/src/types/shared/model-filter.ts

@@ -0,0 +1,15 @@
+/**
+ * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A bare
+ * `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a local
+ * calendar day there.
+ */
+export type WindowStart = Date;
+
+/**
+ * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
+ * exactly `end` is outside it.
+ */
+export type WindowEnd = Date;
+
+/** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */
+export type ModelFilter = string;

package/src/types/shared/not-found-error.ts

@@ -0,0 +1,4 @@
+import type { Error } from './error';
+
+/** Resource not found */
+export type NotFoundError = Error;

package/src/types/shared/page.ts

@@ -0,0 +1,7 @@
+/**
+ * Page number, 1-based.
+ *
+ * @default 1
+ * @minimum 1
+ */
+export type Page = number;

package/src/types/shared/pagination.ts

@@ -0,0 +1,7 @@
+export type Pagination = {
+  limit: number;
+  page: number;
+  /** Total items matching the request. */
+  total: number;
+  totalPages: number;
+};

package/src/types/shared/validation-error.ts

@@ -0,0 +1,4 @@
+import type { Error } from './error';
+
+/** Invalid request data */
+export type ValidationError = Error;

package/src/types/snapshots.ts

@@ -0,0 +1,88 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { MentionsSummary } from './shared/mention-entry';
+import type { NotFoundError } from './shared/not-found-error';
+import type { ValidationError } from './shared/validation-error';
+
+export type CitedURLEntry = {
+  /** Number of times this URL was cited */
+  count: number;
+  /** Page title if available */
+  title: string | null;
+  /** The cited URL */
+  url: string;
+};
+
+export type PromptSnapshot = {
+  /** Brand identifier this prompt belongs to */
+  brandId: string;
+  citations: {
+    /** Number of citations to brand-owned domains */
+    brandCitationsTotal: number;
+    /** Total number of citations across all runs */
+    citationsTotal: number;
+    /** Top-K cited URLs ranked by frequency */
+    citedUrlsTopK: Array<CitedURLEntry>;
+    /** Number of citations to competitor-owned domains */
+    competitorCitationsTotal: number;
+  };
+  /** End of the queried date range (YYYY-MM-DD) */
+  endDate: string;
+  mentions: MentionsSummary;
+  /** Unique identifier for the prompt */
+  promptId: string;
+  /** The prompt text */
+  promptValue: string;
+  /** Start of the queried date range (YYYY-MM-DD) */
+  startDate: string;
+};
+
+export type GetPromptSnapshotErrors = {
+  /** Invalid request data */
+  400: ValidationError;
+  /** Authentication required */
+  401: UnauthorizedError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Resource not found */
+  404: NotFoundError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type GetPromptSnapshotResponses = {
+  /** Prompt snapshot with mention and citation analytics */
+  200: PromptSnapshot;
+};
+
+export type GetPromptSnapshotParams = {
+  /** Start of date range (YYYY-MM-DD) */
+  startDate: string;
+  /** End of date range (YYYY-MM-DD) */
+  endDate: string;
+  /**
+   * Number of top competitor entities to return in mentionsTopK
+   *
+   * @default 5
+   * @minimum 1
+   * @maximum 50
+   */
+  kMentions?: number;
+  /**
+   * Number of top cited URLs to return in citedUrlsTopK
+   *
+   * @default 10
+   * @minimum 1
+   * @maximum 50
+   */
+  kCitations?: number;
+};

package/src/types/tags.ts

@@ -0,0 +1,47 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { NotFoundError } from './shared/not-found-error';
+
+export type Tag = {
+  /** The tag, normalized to lower case. */
+  name: string;
+  /** Prompts in this brand carrying the tag. */
+  promptCount: number;
+  /**
+   * True for `branded` and `unbranded`, which Elmo computes from the prompt text. A system tag
+   * always appears here; applying it to a prompt as a user tag overrides the computed
+   * classification rather than creating a new tag.
+   */
+  system: boolean;
+};
+
+export type TagList = {
+  brandId: string;
+  /** System tags first, then user tags alphabetically — the order the dashboard's filter shows. */
+  data: Array<Tag>;
+};
+
+export type ListBrandTagsErrors = {
+  /** Authentication required */
+  401: UnauthorizedError;
+  /**
+   * The key is valid but not permitted: a missing scope, an admin-only endpoint, or a write in
+   * read-only (demo) mode.
+   */
+  403: ForbiddenError;
+  /** Resource not found */
+  404: NotFoundError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type ListBrandTagsResponses = {
+  /** List a brand's tags */
+  200: TagList;
+};