@elmohq/sdk 0.0.0-stage → 0.1.1

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;
+};

package/src/types/tools.ts

@@ -0,0 +1,78 @@
+import type { ConflictError, PaymentRequiredError } from './shared/conflict-error';
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { ValidationError } from './shared/validation-error';
+
+export type OnboardingSuggestion = {
+  additionalDomains: Array<string>;
+  aliases: Array<string>;
+  brandName: string;
+  competitors: Array<{
+    aliases: Array<string>;
+    domains: Array<string>;
+    name: string;
+  }>;
+  suggestedPrompts: Array<{
+    prompt: string;
+    tags: Array<string>;
+  }>;
+  /** Cleaned hostname */
+  website: string;
+};
+
+export type AnalyzeBrandErrors = {
+  /** 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 AnalyzeBrandResponses = {
+  /** Brand analysis suggestion */
+  200: OnboardingSuggestion;
+};
+
+export type AnalyzeBrandParams = {
+  /**
+   * Brand's website — a hostname or a full URL. A URL with a path (e.g. https://www.nike.com/golf)
+   * is analyzed as given; the returned website is always its domain.
+   *
+   * @minLength 1
+   */
+  website: string;
+  /** Optional brand name hint. If omitted, inferred from the domain. */
+  brandName?: string;
+  /**
+   * Maximum number of competitor suggestions. 0 disables competitor generation entirely.
+   *
+   * @default 20
+   * @minimum 0
+   * @maximum 100
+   */
+  maxCompetitors?: number;
+  /**
+   * Maximum number of suggested prompts. 0 disables prompt generation entirely.
+   *
+   * @default 30
+   * @minimum 0
+   * @maximum 100
+   */
+  maxPrompts?: number;
+};