@elmohq/sdk 0.0.0-stage → 0.1.0

package/src/resources/shared/rule.ts

@@ -0,0 +1,25 @@
+import type { InputRule } from '../../internal/core/types';
+
+export const nameRule: InputRule = {
+  min: 1,
+  name: 'name',
+  of: 'characters',
+};
+
+export const domainsRule: InputRule = {
+  min: 1,
+  name: 'domains',
+  of: 'items',
+};
+
+export const brandNameRule: InputRule = {
+  min: 1,
+  name: 'brandName',
+  of: 'characters',
+};
+
+export const valueRule: InputRule = {
+  min: 1,
+  name: 'value',
+  of: 'characters',
+};

package/src/resources/snapshots.ts

@@ -0,0 +1,54 @@
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { callPromise, RestCallPromise } from '../internal/core/call-promise';
+import { callable } from '../internal/core/callable';
+import { mergeParams, placeParams } from '../internal/core/params';
+import type {
+  CitedURLEntry,
+  GetPromptSnapshotErrors,
+  GetPromptSnapshotParams,
+  GetPromptSnapshotResponses,
+  PromptSnapshot,
+} from '../types/snapshots';
+
+export const getPromptSnapshotFields = { path: ['promptId'] };
+
+export const getPromptSnapshotDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}/snapshot',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+} as const);
+
+/** Aggregated analytics snapshots for prompts */
+export class Snapshot extends ElmoResource {
+  /**
+   * Get an aggregated snapshot of mention and citation analytics for a specific prompt over a date
+   * range. Use this to identify competitive gaps, track brand visibility trends, and discover top
+   * cited URLs.
+   *
+   * @param promptId The ID of the prompt
+   */
+  public get(
+    promptId: string,
+    params: GetPromptSnapshotParams,
+    options?: RequestOptions,
+  ): RestCallPromise<GetPromptSnapshotResponses, GetPromptSnapshotErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getPromptSnapshotDescriptor,
+      mergeParams(placeParams({ ...params, promptId }, getPromptSnapshotFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Snapshot {
+  export type {
+    CitedURLEntry,
+    GetPromptSnapshotErrors,
+    GetPromptSnapshotParams,
+    GetPromptSnapshotResponses,
+    PromptSnapshot,
+  };
+}

package/src/resources/tags.ts

@@ -0,0 +1,46 @@
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { callPromise, RestCallPromise } from '../internal/core/call-promise';
+import { callable } from '../internal/core/callable';
+import { mergeParams, placeParams } from '../internal/core/params';
+import type { BrandIdPath } from '../types/shared/brand-id-path';
+import type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList } from '../types/tags';
+
+export const listBrandTagsFields = { path: ['brandId'] };
+
+export const listBrandTagsDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/tags',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+} as const);
+
+/** The tags in use on a brand's prompts */
+export class Tags extends ElmoResource {
+  /**
+   * List a brand's tags
+   *
+   * Every tag in use on the brand's prompts, with how many carry each — enough to build the same
+   * filter the dashboard shows without paging the whole prompt list to derive it.
+   *
+   * Tags are not a resource of their own: a tag exists exactly as long as some prompt carries it.
+   * `branded` and `unbranded` are computed by Elmo and always listed.
+   *
+   * @param brandId Brand identifier.
+   */
+  public list(
+    brandId: BrandIdPath,
+    options?: RequestOptions,
+  ): RestCallPromise<ListBrandTagsResponses, ListBrandTagsErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      listBrandTagsDescriptor,
+      mergeParams(placeParams({ brandId }, listBrandTagsFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Tags {
+  export type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList };
+}

package/src/resources/tools.ts

@@ -0,0 +1,68 @@
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { callPromise, RestCallPromise } from '../internal/core/call-promise';
+import { callable } from '../internal/core/callable';
+import { groupParams, mergeParams } from '../internal/core/params';
+import type {
+  AnalyzeBrandErrors,
+  AnalyzeBrandParams,
+  AnalyzeBrandResponses,
+  OnboardingSuggestion,
+} from '../types/tools';
+
+export const analyzeBrandDescriptor = /* @__PURE__ */ callable({
+  address: '/tools/analyze',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'post',
+  returns: 'json',
+  rules: [
+    {
+      min: 1,
+      name: 'website',
+      of: 'characters',
+    },
+    {
+      max: 100,
+      min: 0,
+      name: 'maxCompetitors',
+    },
+    {
+      max: 100,
+      min: 0,
+      name: 'maxPrompts',
+    },
+  ],
+} as const);
+
+/** One-shot helpers (e.g. brand analysis) that don't persist anything */
+export class Tools extends ElmoResource {
+  /**
+   * Analyze a website
+   *
+   * Run brand analysis without persisting anything. Returns suggested additional domains, aliases,
+   * competitors, and prompts.
+   *
+   * Requires an instance admin key; organization keys receive `403`.
+   */
+  public analyze(
+    params: AnalyzeBrandParams,
+    options?: RequestOptions,
+  ): RestCallPromise<AnalyzeBrandResponses, AnalyzeBrandErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      analyzeBrandDescriptor,
+      mergeParams(groupParams(params, 'body'), options),
+    );
+  }
+}
+
+export declare namespace Tools {
+  export type {
+    AnalyzeBrandErrors,
+    AnalyzeBrandParams,
+    AnalyzeBrandResponses,
+    OnboardingSuggestion,
+  };
+}

package/src/types/analytics.ts

@@ -0,0 +1,497 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { ModelFilter, WindowEnd, WindowStart } from './shared/model-filter';
+import type { NotFoundError } from './shared/not-found-error';
+import type { ValidationError } from './shared/validation-error';
+
+/**
+ * The window the response was computed over, echoed back as the half-open instants it resolved to.
+ */
+export type DateRange = {
+  /** Exclusive upper bound, in UTC. */
+  end: Date;
+  /** Inclusive lower bound, in UTC. */
+  start: Date;
+};
+
+export type VisibilityPoint = {
+  date: string;
+  /**
+   * Null on days with no runs to plot; the series is not gap-filled with zeros. Ratio 0–1; multiply
+   * by 100 for a percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  visibility: number | null;
+};
+
+export type ShareOfVoiceEntry = {
+  /** True for the tracked brand's own row. */
+  isBrand: boolean;
+  mentions: number;
+  /** Brand or competitor name. */
+  name: string;
+  /** Distinct prompts this entity appeared in. */
+  prompts: number;
+  /**
+   * This entity's share of all brand and competitor mentions. Ratio 0–1; multiply by 100 for a
+   * percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  share: number;
+};
+
+export type ShareOfVoicePoint = {
+  date: string;
+  /**
+   * The brand's share on this day. Null on days with no runs. Ratio 0–1; multiply by 100 for a
+   * percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  share: number | null;
+};
+
+export type CitationDomain = {
+  /** Which side of the citation landscape the domain sits on. */
+  category:
+    | 'brand'
+    | 'competitor'
+    | 'editorial'
+    | 'reviews'
+    | 'ecommerce'
+    | 'social'
+    | 'developer'
+    | 'pr'
+    | 'reference'
+    | 'institutional'
+    | 'other';
+  /**
+   * How this window compares with the equal-length window before it, as a multiplier of the
+   * previous count: 2 means twice as many citations, 0.5 means half, 1 means unchanged. Not a
+   * percentage change — 1.5 is "1.5x", which is a 50% increase. Null when the domain had no
+   * citations in the previous window, so there is nothing to divide by.
+   *
+   * @minimum 0
+   */
+  changeFactor: number | null;
+  /** Citations to this domain in the window. */
+  count: number;
+  domain: string;
+  /** Citations in the equal-length window immediately before this one. */
+  previousCount: number;
+  /** Distinct prompts whose answers cited this domain. */
+  promptCount: number;
+  /**
+   * Share of all citations in the window. Ratio 0–1; multiply by 100 for a percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  share: number;
+};
+
+export type CitationDomainList = {
+  brandId: string;
+  /** Every domain cited over the window, ordered by citation count. */
+  data: Array<CitationDomain>;
+  range: DateRange;
+  totals: {
+    citations: number;
+    uniqueDomains: number;
+    uniqueUrls: number;
+  };
+};
+
+export type CitationURL = {
+  /** Which side of the citation landscape the domain sits on. */
+  category:
+    | 'brand'
+    | 'competitor'
+    | 'editorial'
+    | 'reviews'
+    | 'ecommerce'
+    | 'social'
+    | 'developer'
+    | 'pr'
+    | 'reference'
+    | 'institutional'
+    | 'other';
+  count: number;
+  domain: string;
+  /** Not cited in the equal-length window immediately before this one. */
+  isNew: boolean;
+  /** What kind of page was cited. */
+  pageType:
+    | 'homepage'
+    | 'article'
+    | 'listicle'
+    | 'howto'
+    | 'comparison'
+    | 'review'
+    | 'forum'
+    | 'video'
+    | 'doc'
+    | 'product'
+    | 'info'
+    | 'search'
+    | 'shopping'
+    | 'other';
+  promptCount: number;
+  title: string | null;
+  url: string;
+};
+
+export type CitationURLList = {
+  brandId: string;
+  /** Every URL cited over the window, ordered by citation count. */
+  data: Array<CitationURL>;
+  range: DateRange;
+  totals: {
+    citations: number;
+    uniqueDomains: number;
+    uniqueUrls: number;
+  };
+};
+
+export type FanoutQuery = {
+  promptCount: number;
+  /** A search the engine ran while answering. */
+  query: string;
+  runs: number;
+};
+
+export type BrandQueryFanout = {
+  avgQueriesPerRun: number;
+  brandId: string;
+  /**
+   * Share of fan-out query instances whose answer mentioned the brand. Ratio 0–1; multiply by 100
+   * for a percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  coverageRate: number;
+  /** Every distinct sub-query over the window, ordered by the runs that ran it. */
+  data: Array<FanoutQuery>;
+  /**
+   * Runs that searched at all. Engines that don't expose their searches contribute runs but no
+   * queries.
+   */
+  fanoutRuns: number;
+  range: DateRange;
+  totalQueries: number;
+  totalRuns: number;
+  uniqueQueries: number;
+};
+
+export type PromptPerformance = {
+  /**
+   * Share of this prompt's runs mentioning the brand. Ratio 0–1; multiply by 100 for a percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  brandMentionRate: number;
+  /**
+   * Share of this prompt's runs mentioning any tracked competitor. Ratio 0–1; multiply by 100 for a
+   * percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  competitorMentionRate: number;
+  firstEvaluatedAt: Date | null;
+  lastRunAt: Date | null;
+  promptId: string;
+  tags: Array<string>;
+  totalRuns: number;
+  value: string;
+};
+
+export type PromptPerformanceList = {
+  brandId: string;
+  /** Every prompt sampled over the window, with its results. */
+  data: Array<PromptPerformance>;
+  range: DateRange;
+};
+
+export type ModelVisibility = {
+  brandMentions: number;
+  citations: number;
+  label: string;
+  model: string;
+  runs: number;
+  /**
+   * Share of this model's runs that mentioned the brand. Ratio 0–1; multiply by 100 for a
+   * percentage.
+   *
+   * @minimum 0
+   * @maximum 1
+   */
+  visibility: number | null;
+};
+
+/**
+ * Every non-paginated figure for a brand over one window. There is no parameter for selecting a
+ * subset: the four computations behind this share one scope resolution and run concurrently, so a
+ * subset would save a caller a fraction of one request and cost everyone a parameter to reason
+ * about.
+ */
+export type BrandAnalytics = {
+  brandId: string;
+  brandName: string;
+  /** Per-model visibility and run counts. Only models that produced a run in the window appear. */
+  models: Array<ModelVisibility>;
+  range: DateRange;
+  /** The brand against its tracked competitors. */
+  shareOfVoice: {
+    /**
+     * The brand's own share at the end of the window. Ratio 0–1; multiply by 100 for a percentage.
+     *
+     * @minimum 0
+     * @maximum 1
+     */
+    brand: number | null;
+    /** Leaderboard, highest share first. */
+    entries: Array<ShareOfVoiceEntry>;
+    /** The brand's share over time. */
+    series: Array<ShareOfVoicePoint>;
+  };
+  totals: {
+    citations: number;
+    /** Enabled prompts counted in the window. */
+    prompts: number;
+    runs: number;
+    uniqueDomains: number;
+    uniqueUrls: number;
+  };
+  /** How often the brand is mentioned at all. */
+  visibility: {
+    /**
+     * The last plotted point — the number the dashboard hero shows. Ratio 0–1; multiply by 100 for
+     * a percentage.
+     *
+     * @minimum 0
+     * @maximum 1
+     */
+    current: number | null;
+    series: Array<VisibilityPoint>;
+  };
+};
+
+/** Comma-separated prompt tags. Only prompts carrying at least one of them are counted. */
+export type TagsFilter = string;
+
+export type GetBrandAnalyticsErrors = {
+  /** 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 GetBrandAnalyticsResponses = {
+  /** Get a brand's analytics */
+  200: BrandAnalytics;
+};
+
+export type ListBrandCitationDomainsErrors = {
+  /** 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 ListBrandCitationDomainsResponses = {
+  /** List cited domains */
+  200: CitationDomainList;
+};
+
+export type ListBrandCitationURLsErrors = {
+  /** 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 ListBrandCitationURLsResponses = {
+  /** List cited URLs */
+  200: CitationURLList;
+};
+
+export type ListBrandPromptPerformanceErrors = {
+  /** 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 ListBrandPromptPerformanceResponses = {
+  /** List prompt performance */
+  200: PromptPerformanceList;
+};
+
+export type GetBrandQueryFanoutErrors = {
+  /** 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 GetBrandQueryFanoutResponses = {
+  /** Get query fan-out */
+  200: BrandQueryFanout;
+};
+
+export type GetBrandAnalyticsParams = {
+  /**
+   * 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;
+  /** Comma-separated prompt tags. Only prompts carrying at least one of them are counted. */
+  tags?: TagsFilter;
+};
+
+export type ListBrandCitationDomainsParams = {
+  /**
+   * 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;
+  /** Comma-separated prompt tags. Only prompts carrying at least one of them are counted. */
+  tags?: TagsFilter;
+};
+
+export type ListBrandCitationURLsParams = {
+  /**
+   * 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;
+  /** Comma-separated prompt tags. Only prompts carrying at least one of them are counted. */
+  tags?: TagsFilter;
+};
+
+export type ListBrandPromptPerformanceParams = {
+  /**
+   * 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;
+  /** Comma-separated prompt tags. Only prompts carrying at least one of them are counted. */
+  tags?: TagsFilter;
+};
+
+export type GetBrandQueryFanoutParams = {
+  /**
+   * 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;
+  /** Comma-separated prompt tags. Only prompts carrying at least one of them are counted. */
+  tags?: TagsFilter;
+};