@elmohq/sdk 0.0.0-stage → 0.1.1

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

package/src/types/opportunities.ts

@@ -0,0 +1,84 @@
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { NotFoundError } from './shared/not-found-error';
+
+export type OpportunityPrompt = {
+  /** The tracked prompt it resolved to, or null when it didn't match one. */
+  promptId: string | null;
+  /** The prompt as the report names it. */
+  text: string;
+};
+
+export type CitedPage = {
+  domain: string;
+  title: string | null;
+  url: string;
+};
+
+export type Opportunity = {
+  /**
+   * Which workstream this belongs to: `creation` is net-new content, `existing-content` is a page
+   * that could win the mention with a refresh, `outreach` is earning a placement on a third-party
+   * site assistants cite, `social` is the community conversations they pull from.
+   */
+  category: 'creation' | 'existing-content' | 'outreach' | 'social';
+  /** Pages on competitor domains cited for those prompts. */
+  competitorCitations: Array<CitedPage>;
+  /** Tracked prompts this would help. May be empty. */
+  relatedPrompts: Array<OpportunityPrompt>;
+  /** Short and action-oriented — the concrete surface or angle. */
+  title: string;
+  /** Why it is worth doing, in plain language. */
+  why: string;
+  /** Pages on the brand's own domains already cited for those prompts. */
+  yourCitations: Array<CitedPage>;
+};
+
+/**
+ * The brand's latest Opportunities report — the same LLM-generated analysis the dashboard shows,
+ * read from the append-only history rather than regenerated. Elmo decides when to produce a new
+ * one; there is no way to trigger generation over the API, because it spends provider budget with
+ * no per-call metering behind it.
+ */
+export type BrandOpportunities = {
+  brandId: string;
+  generatedAt: Date | null;
+  /** The model that produced the report, when recorded. */
+  model: string | null;
+  /** Prioritized, highest impact first. */
+  opportunities: Array<Opportunity>;
+  /** Caveats: hard-to-win areas, or tactics to avoid. */
+  risks: Array<string>;
+  /**
+   * `ready` when a report is present. `insufficient-data` when the brand hasn't accumulated enough
+   * tracked answers to say anything useful yet, in which case the lists are empty.
+   */
+  status: 'ready' | 'insufficient-data';
+  /** A few bullets on where the brand stands and the through-line of the plan. */
+  summary: Array<string>;
+};
+
+export type GetBrandOpportunitiesErrors = {
+  /** 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 GetBrandOpportunitiesResponses = {
+  /** Get the latest opportunities report */
+  200: BrandOpportunities;
+};

package/src/types/organizations.ts

@@ -0,0 +1,157 @@
+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';
+
+export type Organization = {
+  brandCount: number;
+  createdAt: Date;
+  id: string;
+  name: string;
+  slug: string;
+};
+
+/** The organization's plan limits. Every field is null on deployments without billing. */
+export type PlanLimits = {
+  /** Null means no limit. */
+  maxBrands: number | null;
+  /** Enabled prompts across the whole organization. Null means no limit. */
+  maxPrompts: number | null;
+  /** Models the plan may pick from. Null means any. */
+  modelMenu: Array<string> | null;
+  /** Models trackable per brand. */
+  modelPicks: number | null;
+  /** Prompt/model pairings trackable grounded. */
+  premiumPool: number;
+  premiumRunsPerDay: number;
+  standardRunsPerDay: number | null;
+};
+
+/**
+ * Read-only view of an organization's subscription, limits, and usage. The API has no way to change
+ * any of it: there is no billing write endpoint and no billing write scope. Stripe identifiers,
+ * payment methods, and invoices are deliberately not exposed — those live in the Stripe customer
+ * portal.
+ */
+export type OrganizationBilling = {
+  /** False on self-hosted deployments, where nothing is metered. */
+  billingEnabled: boolean;
+  limits: PlanLimits | null;
+  organizationId: string;
+  /** Null when the organization has no subscription, or when billing is disabled. */
+  plan: BillingPlan | null;
+  usage: {
+    brands: number;
+    enabledPrompts: number;
+    premiumPairingsAssigned: number;
+  };
+};
+
+export type BillingPlan = {
+  cancelAtPeriodEnd: boolean;
+  /** Null on a negotiated plan, which carries no billing interval. */
+  interval?: 'monthly' | 'annual' | null;
+  /** Plan identifier, or `custom` for a negotiated plan. */
+  key: string | null;
+  /** Display name. */
+  name: string;
+  periodEnd?: Date | null;
+  /**
+   * What the subscription means for service, and the only field a caller needs to act on: `active`
+   * and `grace` keep tracking running, `paused` stops it, `none` is unsubscribed. The payment
+   * provider's own status string is deliberately not passed through.
+   */
+  standing: 'active' | 'grace' | 'paused' | 'none';
+  /** Whether prompts are currently being sampled. */
+  trackingActive: boolean;
+};
+
+export type OrganizationList = {
+  data: Array<Organization>;
+  pagination: Pagination;
+};
+
+export type ListOrganizationsErrors = {
+  /** 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 ListOrganizationsResponses = {
+  /** List organizations */
+  200: OrganizationList;
+};
+
+export type GetOrganizationErrors = {
+  /** 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 GetOrganizationResponses = {
+  /** Get an organization */
+  200: Organization;
+};
+
+export type GetOrganizationBillingErrors = {
+  /** 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 GetOrganizationBillingResponses = {
+  /** Get billing state */
+  200: OrganizationBilling;
+};
+
+export type ListOrganizationsParams = {
+  /**
+   * 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;
+};