@elmohq/sdk 0.0.0-stage → 0.1.0

package/src/types/brands.ts

@@ -0,0 +1,228 @@
+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 { 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';
+
+export type Brand = {
+  aliases: Array<string>;
+  createdAt: Date;
+  /** Sampling cadence override in hours. Null means the plan cadence. */
+  delayOverrideHours: number | null;
+  /**
+   * Brand domains. The first entry is the primary website; remaining entries are additional
+   * domains.
+   */
+  domains: Array<string>;
+  enabled: boolean;
+  /** Models this brand is tracked on. Null means the deployment default. */
+  enabledModels: Array<string> | null;
+  /** User-supplied brand identifier (e.g. "acme") */
+  id: string;
+  name: string;
+  onboarded: boolean;
+  /** The organization that owns this brand and is billed for it. */
+  organizationId: string;
+  updatedAt: Date;
+};
+
+export type BrandsList = {
+  /**
+   * Deprecated: read `data` instead. Kept while the one known consumer migrates, and removed in a
+   * future release.
+   *
+   * @deprecated
+   */
+  brands: Array<Brand>;
+  /** The items on this page. Read this rather than the named key below. */
+  data: Array<Brand>;
+  pagination: Pagination;
+};
+
+export type ListBrandsErrors = {
+  /** 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 ListBrandsResponses = {
+  /** Paginated list of brands */
+  200: BrandsList;
+};
+
+export type CreateBrandErrors = {
+  /** 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 not found */
+  404: NotFoundError;
+  /** Resource already exists */
+  409: ConflictError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type CreateBrandResponses = {
+  /** Brand created */
+  201: Brand;
+};
+
+export type GetBrandErrors = {
+  /** 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 GetBrandResponses = {
+  /** Brand */
+  200: Brand;
+};
+
+export type UpdateBrandErrors = {
+  /** 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 not found */
+  404: NotFoundError;
+  /** Resource already exists */
+  409: ConflictError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type UpdateBrandResponses = {
+  /** Brand updated */
+  200: Brand;
+};
+
+export type ListBrandsParams = {
+  /**
+   * 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;
+};
+
+/**
+ * Create a brand. Skips onboarding. The first entry in `domains` is treated as the brand's primary
+ * website; the rest are stored as additional domains.
+ */
+export type CreateBrandParams = {
+  /** @minLength 1 */
+  id: string;
+  /** @minLength 1 */
+  name: string;
+  /**
+   * Brand domains. The first entry is the primary website; remaining entries are additional
+   * domains.
+   *
+   * @minItems 1
+   */
+  domains: Array<string>;
+  aliases?: Array<string>;
+  competitors?: Array<{
+    aliases?: Array<string>;
+    domains?: Array<string>;
+    /** @minLength 1 */
+    name: string;
+  }>;
+  prompts?: Array<{
+    /** @default true */
+    enabled?: boolean;
+    tags?: Array<string>;
+    /** @minLength 1 */
+    value: string;
+  }>;
+  /**
+   * Organization to create the brand in.
+   *
+   * | | Omitted | Present |
+   * | --- | --- | --- |
+   * | **Organization key** | creates in the key's own organization | must name the key's own organization; any other value is a `400` |
+   * | **Admin key** | provisions a new organization named after the brand id | creates in the named organization, which must already exist — `404` if it does not |
+   *
+   * An admin key omitting this field is currently the only way to create an organization over the
+   * API.
+   */
+  organizationId?: string;
+};
+
+/**
+ * Update brand-level fields. At least one field must be provided. Provided arrays replace the
+ * stored values verbatim. When `domains` is provided, the first entry becomes the primary website
+ * and the rest become additional domains. Prompts and competitors are managed via /prompts and
+ * /competitors.
+ */
+export type UpdateBrandParams = {
+  /** @minLength 1 */
+  brandName?: string;
+  /**
+   * Brand domains. The first entry is the primary website; remaining entries are additional
+   * domains.
+   *
+   * @minItems 1
+   */
+  domains?: Array<string>;
+  aliases?: Array<string>;
+  /**
+   * Whether the brand is sampled at all. **Modifiable only with an instance admin key**: setting it
+   * with an organization key is a `403`, because disabling ends tracking silently while the plan
+   * keeps being billed and no dashboard control does it at any role.
+   */
+  enabled?: boolean;
+};

package/src/types/competitors.ts

@@ -0,0 +1,196 @@
+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 { 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';
+
+export type Competitor = {
+  aliases: Array<string>;
+  brandId: string;
+  createdAt: Date;
+  domains: Array<string>;
+  id: string;
+  name: string;
+  updatedAt: Date;
+};
+
+export type CompetitorsList = {
+  /**
+   * Deprecated: read `data` instead. Kept while the one known consumer migrates, and removed in a
+   * future release.
+   *
+   * @deprecated
+   */
+  competitors: Array<Competitor>;
+  /** The items on this page. Read this rather than the named key below. */
+  data: Array<Competitor>;
+  pagination: Pagination;
+};
+
+export type ListCompetitorsErrors = {
+  /** 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 ListCompetitorsResponses = {
+  /** Paginated list of competitors */
+  200: CompetitorsList;
+};
+
+export type CreateCompetitorErrors = {
+  /** 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 CreateCompetitorResponses = {
+  /** Competitor created */
+  201: Competitor;
+};
+
+export type DeleteCompetitorErrors = {
+  /** 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 not found */
+  404: NotFoundError;
+  /** Resource already exists */
+  409: ConflictError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type DeleteCompetitorResponses = {
+  /** Competitor deleted (returns the deleted competitor) */
+  200: Competitor;
+};
+
+export type GetCompetitorErrors = {
+  /** 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 GetCompetitorResponses = {
+  /** Competitor */
+  200: Competitor;
+};
+
+export type UpdateCompetitorErrors = {
+  /** 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 not found */
+  404: NotFoundError;
+  /** Resource already exists */
+  409: ConflictError;
+  /** Per-key rate limit exceeded. */
+  429: RateLimitError;
+  /** Internal server error */
+  500: InternalServerError;
+};
+
+export type UpdateCompetitorResponses = {
+  /** Competitor updated */
+  200: Competitor;
+};
+
+export type ListCompetitorsParams = {
+  brandId?: string;
+  /**
+   * 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;
+};
+
+/** Add a competitor to a brand. */
+export type CreateCompetitorParams = {
+  /** @minLength 1 */
+  brandId: string;
+  /** @minLength 1 */
+  name: string;
+  domains?: Array<string>;
+  aliases?: Array<string>;
+};
+
+/**
+ * Update a competitor. At least one field must be provided. Provided arrays replace the stored
+ * values verbatim.
+ */
+export type UpdateCompetitorParams = {
+  /** @minLength 1 */
+  name?: string;
+  domains?: Array<string>;
+  aliases?: Array<string>;
+};

package/src/types/identity.ts

@@ -0,0 +1,55 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+
+export type APIKeyIdentity = {
+  /**
+   * Brands the key is narrowed to, or null when it reaches every brand in its organization. Never
+   * an empty array — a restriction to no brands is rejected at creation rather than treated as no
+   * restriction.
+   */
+  brandIds: Array<string> | null;
+  createdAt: Date | null;
+  /** The key's label, as given when it was issued. Null for admin keys. */
+  createdBy: string | null;
+  /** When the key stops working, if it has an expiry. */
+  expiresAt: Date | null;
+  /** `admin` for an instance key, `organization` for a dashboard-issued key. */
+  keyType: 'admin' | 'organization';
+  lastUsedAt: Date | null;
+  /** The organization this key acts inside. Null for admin keys. */
+  organizationId: string | null;
+  organizationName: string | null;
+  /**
+   * The key's configured limit — generous by design: it exists to stop a runaway loop, not to meter
+   * normal use. Enforcement is a fixed window and approximate under concurrency.
+   */
+  rateLimit: {
+    limit: number;
+    window: 'minute' | 'hour';
+  } | null;
+  /** Scopes this key holds. A read-write key lists both; an admin key always does. */
+  scopes: Array<'read' | 'write'>;
+};
+
+export type GetMeErrors = {
+  /** 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 GetMeResponses = {
+  /** Describe the calling key */
+  200: APIKeyIdentity;
+};

package/src/types/index.ts

@@ -0,0 +1,163 @@
+export type {
+  BrandAnalytics,
+  BrandQueryFanout,
+  CitationDomain,
+  CitationDomainList,
+  CitationURL,
+  CitationURLList,
+  DateRange,
+  FanoutQuery,
+  GetBrandAnalyticsErrors,
+  GetBrandAnalyticsParams,
+  GetBrandAnalyticsResponses,
+  GetBrandQueryFanoutErrors,
+  GetBrandQueryFanoutParams,
+  GetBrandQueryFanoutResponses,
+  ListBrandCitationDomainsErrors,
+  ListBrandCitationDomainsParams,
+  ListBrandCitationDomainsResponses,
+  ListBrandCitationURLsErrors,
+  ListBrandCitationURLsParams,
+  ListBrandCitationURLsResponses,
+  ListBrandPromptPerformanceErrors,
+  ListBrandPromptPerformanceParams,
+  ListBrandPromptPerformanceResponses,
+  ModelVisibility,
+  PromptPerformance,
+  PromptPerformanceList,
+  ShareOfVoiceEntry,
+  ShareOfVoicePoint,
+  TagsFilter,
+  VisibilityPoint,
+} from './analytics';
+export type {
+  Brand,
+  BrandsList,
+  CreateBrandErrors,
+  CreateBrandParams,
+  CreateBrandResponses,
+  GetBrandErrors,
+  GetBrandResponses,
+  ListBrandsErrors,
+  ListBrandsParams,
+  ListBrandsResponses,
+  UpdateBrandErrors,
+  UpdateBrandParams,
+  UpdateBrandResponses,
+} from './brands';
+export type {
+  Competitor,
+  CompetitorsList,
+  CreateCompetitorErrors,
+  CreateCompetitorParams,
+  CreateCompetitorResponses,
+  DeleteCompetitorErrors,
+  DeleteCompetitorResponses,
+  GetCompetitorErrors,
+  GetCompetitorResponses,
+  ListCompetitorsErrors,
+  ListCompetitorsParams,
+  ListCompetitorsResponses,
+  UpdateCompetitorErrors,
+  UpdateCompetitorParams,
+  UpdateCompetitorResponses,
+} from './competitors';
+export type { APIKeyIdentity, GetMeErrors, GetMeResponses } from './identity';
+export type { ListModelsErrors, ListModelsResponses, Model, ModelList } from './models';
+export type {
+  BrandOpportunities,
+  CitedPage,
+  GetBrandOpportunitiesErrors,
+  GetBrandOpportunitiesResponses,
+  Opportunity,
+  OpportunityPrompt,
+} from './opportunities';
+export type {
+  BillingPlan,
+  GetOrganizationBillingErrors,
+  GetOrganizationBillingResponses,
+  GetOrganizationErrors,
+  GetOrganizationResponses,
+  ListOrganizationsErrors,
+  ListOrganizationsParams,
+  ListOrganizationsResponses,
+  Organization,
+  OrganizationBilling,
+  OrganizationList,
+  PlanLimits,
+} from './organizations';
+export type {
+  CreatePromptErrors,
+  CreatePromptParams,
+  CreatePromptResponses,
+  DeletePromptErrors,
+  DeletePromptResponse,
+  DeletePromptResponses,
+  GetPromptErrors,
+  GetPromptResponses,
+  ListPromptsErrors,
+  ListPromptsParams,
+  ListPromptsResponse,
+  ListPromptsResponses,
+  Prompt,
+  UpdatePromptErrors,
+  UpdatePromptParams,
+  UpdatePromptResponses,
+} from './prompts';
+export type {
+  CreateReportErrors,
+  CreateReportParams,
+  CreateReportResponse,
+  CreateReportResponses,
+  GetReportErrors,
+  GetReportParams,
+  GetReportResponse,
+  GetReportResponses,
+  ListReportsErrors,
+  ListReportsParams,
+  ListReportsResponse,
+  ListReportsResponses,
+  ReportPromptSnapshot,
+  ReportSummary,
+} from './reports';
+export type {
+  GetRunErrors,
+  GetRunResponses,
+  ListPromptRunsErrors,
+  ListPromptRunsParams,
+  ListPromptRunsResponses,
+  Run,
+  RunCitation,
+  RunList,
+  RunSummary,
+} from './runs';
+export type { BrandIdPath } from './shared/brand-id-path';
+export type { ConflictError, PaymentRequiredError } from './shared/conflict-error';
+export type {
+  Error,
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+export type { Limit } from './shared/limit';
+export type { MentionEntry, MentionsSummary } from './shared/mention-entry';
+export type { ModelFilter, WindowEnd, WindowStart } from './shared/model-filter';
+export type { NotFoundError } from './shared/not-found-error';
+export type { Page } from './shared/page';
+export type { Pagination } from './shared/pagination';
+export type { ValidationError } from './shared/validation-error';
+export type {
+  CitedURLEntry,
+  GetPromptSnapshotErrors,
+  GetPromptSnapshotParams,
+  GetPromptSnapshotResponses,
+  PromptSnapshot,
+} from './snapshots';
+export type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList } from './tags';
+export type {
+  AnalyzeBrandErrors,
+  AnalyzeBrandParams,
+  AnalyzeBrandResponses,
+  OnboardingSuggestion,
+} from './tools';

package/src/types/models.ts

@@ -0,0 +1,40 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+
+export type ModelList = {
+  data: Array<Model>;
+};
+
+export type Model = {
+  /** Whether this deployment is actually wired to reach it. */
+  configured: boolean;
+  /** Identifier used by the `model` filter, e.g. `chatgpt`. */
+  id: string;
+  /** Human-readable name. */
+  label: string;
+  /** Whether this model can be tracked grounded, spending a premium pairing. */
+  premiumCapable: boolean;
+};
+
+export type ListModelsErrors = {
+  /** 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 ListModelsResponses = {
+  /** List trackable models */
+  200: ModelList;
+};