@elmohq/sdk 0.0.0-stage → 0.1.0

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

package/src/types/prompts.ts

@@ -0,0 +1,231 @@
+import type { ConflictError, PaymentRequiredError } from './shared/conflict-error';
+import type {
+  ForbiddenError,
+  InternalServerError,
+  RateLimitError,
+  UnauthorizedError,
+} from './shared/error';
+import type { NotFoundError } from './shared/not-found-error';
+import type { Page } from './shared/page';
+import type { ValidationError } from './shared/validation-error';
+
+export type Prompt = {
+  /** Brand identifier this prompt belongs to */
+  brandId: string;
+  /** Timestamp when the prompt was created */
+  createdAt: Date;
+  /** Whether the prompt is currently enabled */
+  enabled: boolean;
+  /** Unique identifier for the prompt */
+  id: string;
+  /** Models this prompt is tracked on grounded. Each entry spends one premium pairing. */
+  premiumModels: Array<string>;
+  /** Auto-computed system tags (e.g., 'branded', 'unbranded'). Read-only. */
+  systemTags: Array<string>;
+  /** User-defined tags for categorizing this prompt */
+  tags: Array<string>;
+  /** Timestamp when the prompt was last updated */
+  updatedAt: Date;
+  /** The actual prompt text */
+  value: string;
+};
+
+export type ListPromptsErrors = {
+  /** 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 ListPromptsResponses = {
+  /** List of prompts */
+  200: {
+    /** The items on this page. Read this rather than the named key below. */
+    data: Array<Prompt>;
+    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
+     */
+    prompts: Array<Prompt>;
+  };
+};
+
+export type ListPromptsResponse = ListPromptsResponses[keyof ListPromptsResponses];
+
+export type CreatePromptErrors = {
+  /** 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 CreatePromptResponses = {
+  /** Prompt created successfully */
+  201: Prompt;
+};
+
+export type DeletePromptErrors = {
+  /** 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 DeletePromptResponses = {
+  /** Prompt deleted (returns the deleted prompt) */
+  200: Prompt & {
+    /** Number of related prompt_runs rows deleted by the cascade. */
+    deletedRunsCount: number;
+  };
+};
+
+export type DeletePromptResponse = DeletePromptResponses[keyof DeletePromptResponses];
+
+export type GetPromptErrors = {
+  /** 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 GetPromptResponses = {
+  /** Prompt details */
+  200: Prompt;
+};
+
+export type UpdatePromptErrors = {
+  /** 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 UpdatePromptResponses = {
+  /** Prompt updated successfully */
+  200: Prompt;
+};
+
+export type ListPromptsParams = {
+  /** Filter prompts by brand ID */
+  brandId?: string;
+  /**
+   * Page number, 1-based.
+   *
+   * @default 1
+   * @minimum 1
+   */
+  page?: Page;
+  /**
+   * Items per page. Values above the maximum are clamped, not rejected. This list had no ceiling
+   * before, so the maximum is set to bound a runaway query rather than to change what an existing
+   * caller gets back.
+   *
+   * @default 20
+   * @minimum 1
+   * @maximum 1000
+   */
+  limit?: number;
+  /** Only prompts with this tracking state. */
+  enabled?: boolean;
+  /** Comma-separated tags. A prompt matches if it carries any of them. */
+  tags?: string;
+  /** Case-insensitive substring match on prompt text. */
+  q?: string;
+};
+
+export type CreatePromptParams = {
+  /** Brand identifier this prompt belongs to */
+  brandId: string;
+  /**
+   * The prompt text
+   *
+   * @minLength 1
+   */
+  value: string;
+  /** User-defined tags for categorizing this prompt */
+  tags?: Array<string>;
+};
+
+export type UpdatePromptParams = {
+  /**
+   * The prompt text
+   *
+   * @minLength 1
+   */
+  value?: string;
+  /** Whether the prompt is enabled */
+  enabled?: boolean;
+  /** User-defined tags for categorizing this prompt */
+  tags?: Array<string>;
+  /** Replaces the prompt's grounded models. Checked against the organization's premium pool. */
+  premiumModels?: Array<string>;
+};