@elmohq/sdk 0.0.0-stage → 0.1.0

package/src/resources/analytics.ts

@@ -0,0 +1,363 @@
+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 { decoded, reviving } from '../internal/feature/validate';
+import 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,
+  PromptPerformanceList,
+  PromptPerformance as PromptPerformanceSchema,
+  ShareOfVoiceEntry,
+  ShareOfVoicePoint,
+  VisibilityPoint,
+} from '../types/analytics';
+import type { BrandIdPath } from '../types/shared/brand-id-path';
+
+export const getBrandAnalyticsFields = { path: ['brandId'] };
+
+function reviveDateRange(value: DateRange): void {
+  if (value.start != null) {
+    value.start = decoded('DateRange.start', value.start, (raw) => new Date(raw));
+  }
+  if (value.end != null) {
+    value.end = decoded('DateRange.end', value.end, (raw) => new Date(raw));
+  }
+}
+
+function reviveBrandAnalytics(value: BrandAnalytics): void {
+  if (value.range != null) {
+    reviveDateRange(value.range);
+  }
+}
+
+export const getBrandAnalyticsDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/analytics',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveBrandAnalytics) },
+} as const);
+
+export const listBrandCitationDomainsFields = { path: ['brandId'] };
+
+function reviveCitationDomainList(value: CitationDomainList): void {
+  if (value.range != null) {
+    reviveDateRange(value.range);
+  }
+}
+
+export const listBrandCitationDomainsDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/citations/domains',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveCitationDomainList) },
+} as const);
+
+export const listBrandCitationUrlsFields = { path: ['brandId'] };
+
+function reviveCitationUrlList(value: CitationURLList): void {
+  if (value.range != null) {
+    reviveDateRange(value.range);
+  }
+}
+
+export const listBrandCitationURLsDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/citations/urls',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveCitationUrlList) },
+} as const);
+
+export const listBrandPromptPerformanceFields = { path: ['brandId'] };
+
+function revivePromptPerformance(value: PromptPerformanceSchema): void {
+  if (value.lastRunAt != null) {
+    value.lastRunAt = decoded(
+      'PromptPerformance.lastRunAt',
+      value.lastRunAt,
+      (raw) => new Date(raw),
+    );
+  }
+  if (value.firstEvaluatedAt != null) {
+    value.firstEvaluatedAt = decoded(
+      'PromptPerformance.firstEvaluatedAt',
+      value.firstEvaluatedAt,
+      (raw) => new Date(raw),
+    );
+  }
+}
+
+function revivePromptPerformanceList(value: PromptPerformanceList): void {
+  if (value.range != null) {
+    reviveDateRange(value.range);
+  }
+  if (value.data != null) {
+    value.data.forEach((item) => {
+      revivePromptPerformance(item);
+    });
+  }
+}
+
+export const listBrandPromptPerformanceDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/prompt-performance',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(revivePromptPerformanceList) },
+} as const);
+
+export const getBrandQueryFanoutFields = { path: ['brandId'] };
+
+function reviveBrandQueryFanout(value: BrandQueryFanout): void {
+  if (value.range != null) {
+    reviveDateRange(value.range);
+  }
+}
+
+export const getBrandQueryFanoutDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/query-fanout',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveBrandQueryFanout) },
+} as const);
+
+/** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+export class Analytics extends ElmoResource {
+  /**
+   * Get a brand's analytics
+   *
+   * Visibility, share of voice, the per-model breakdown and the citation totals for one window, in
+   * one request.
+   *
+   * The long lists — cited domains and URLs, sub-queries, per-prompt results — are endpoints of
+   * their own. Everything else is always included.
+   *
+   * @param brandId Brand identifier.
+   */
+  public get(
+    brandId: BrandIdPath,
+    params: GetBrandAnalyticsParams,
+    options?: RequestOptions,
+  ): RestCallPromise<GetBrandAnalyticsResponses, GetBrandAnalyticsErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getBrandAnalyticsDescriptor,
+      mergeParams(placeParams({ ...params, brandId }, getBrandAnalyticsFields, 'query'), options),
+    );
+  }
+}
+
+/** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+export class Domains extends ElmoResource {
+  /**
+   * List cited domains
+   *
+   * Domains the engines cited when answering this brand's prompts, categorized and compared against
+   * the equal-length window immediately before this one.
+   *
+   * @param brandId Brand identifier.
+   */
+  public list(
+    brandId: BrandIdPath,
+    params: ListBrandCitationDomainsParams,
+    options?: RequestOptions,
+  ): RestCallPromise<ListBrandCitationDomainsResponses, ListBrandCitationDomainsErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      listBrandCitationDomainsDescriptor,
+      mergeParams(
+        placeParams({ ...params, brandId }, listBrandCitationDomainsFields, 'query'),
+        options,
+      ),
+    );
+  }
+}
+
+/** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+export class URLs extends ElmoResource {
+  /**
+   * List cited URLs
+   *
+   * Individual pages the engines cited, with their category and page type.
+   *
+   * @param brandId Brand identifier.
+   */
+  public list(
+    brandId: BrandIdPath,
+    params: ListBrandCitationURLsParams,
+    options?: RequestOptions,
+  ): RestCallPromise<ListBrandCitationURLsResponses, ListBrandCitationURLsErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      listBrandCitationURLsDescriptor,
+      mergeParams(
+        placeParams({ ...params, brandId }, listBrandCitationUrlsFields, 'query'),
+        options,
+      ),
+    );
+  }
+}
+
+export class Citations extends ElmoResource {
+  private _domains?: Domains;
+  /** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+  get domains(): Domains {
+    return (this._domains ??= new Domains(this.client));
+  }
+
+  private _urls?: URLs;
+  /** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+  get urls(): URLs {
+    return (this._urls ??= new URLs(this.client));
+  }
+}
+
+/** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+export class PromptPerformance extends ElmoResource {
+  /**
+   * List prompt performance
+   *
+   * Per-prompt mention rates over the window. The analytics counterpart to `GET /prompts?brandId=`,
+   * which returns prompt configuration rather than results.
+   *
+   * A prompt the brand stopped tracking is not sampled, so it has no results over the window and
+   * does not appear here.
+   *
+   * @param brandId Brand identifier.
+   */
+  public list(
+    brandId: BrandIdPath,
+    params: ListBrandPromptPerformanceParams,
+    options?: RequestOptions,
+  ): RestCallPromise<ListBrandPromptPerformanceResponses, ListBrandPromptPerformanceErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      listBrandPromptPerformanceDescriptor,
+      mergeParams(
+        placeParams({ ...params, brandId }, listBrandPromptPerformanceFields, 'query'),
+        options,
+      ),
+    );
+  }
+}
+
+/** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+export class QueryFanout extends ElmoResource {
+  /**
+   * Get query fan-out
+   *
+   * The searches engines ran while answering this brand's prompts. Engines that don't expose their
+   * searches still contribute runs, so `coverageRate` is the honest denominator.
+   *
+   * @param brandId Brand identifier.
+   */
+  public get(
+    brandId: BrandIdPath,
+    params: GetBrandQueryFanoutParams,
+    options?: RequestOptions,
+  ): RestCallPromise<GetBrandQueryFanoutResponses, GetBrandQueryFanoutErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getBrandQueryFanoutDescriptor,
+      mergeParams(placeParams({ ...params, brandId }, getBrandQueryFanoutFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Analytics {
+  export type {
+    BrandAnalytics,
+    GetBrandAnalyticsErrors,
+    GetBrandAnalyticsParams,
+    GetBrandAnalyticsResponses,
+    ModelVisibility,
+    ShareOfVoiceEntry,
+    ShareOfVoicePoint,
+    VisibilityPoint,
+  };
+}
+
+export declare namespace Domains {
+  export type {
+    CitationDomain,
+    CitationDomainList,
+    ListBrandCitationDomainsErrors,
+    ListBrandCitationDomainsParams,
+    ListBrandCitationDomainsResponses,
+  };
+}
+
+export declare namespace URLs {
+  export type {
+    CitationURL,
+    CitationURLList,
+    ListBrandCitationURLsErrors,
+    ListBrandCitationURLsParams,
+    ListBrandCitationURLsResponses,
+  };
+}
+
+export declare namespace Citations {
+  export type {
+    CitationDomain,
+    CitationDomainList,
+    CitationURL,
+    CitationURLList,
+    Domains,
+    ListBrandCitationDomainsErrors,
+    ListBrandCitationDomainsParams,
+    ListBrandCitationDomainsResponses,
+    ListBrandCitationURLsErrors,
+    ListBrandCitationURLsParams,
+    ListBrandCitationURLsResponses,
+    URLs,
+  };
+}
+
+export declare namespace PromptPerformance {
+  export type {
+    ListBrandPromptPerformanceErrors,
+    ListBrandPromptPerformanceParams,
+    ListBrandPromptPerformanceResponses,
+    PromptPerformanceSchema as PromptPerformance,
+    PromptPerformanceList,
+  };
+}
+
+export declare namespace QueryFanout {
+  export type {
+    BrandQueryFanout,
+    FanoutQuery,
+    GetBrandQueryFanoutErrors,
+    GetBrandQueryFanoutParams,
+    GetBrandQueryFanoutResponses,
+  };
+}

package/src/resources/brands.ts

@@ -0,0 +1,285 @@
+import { Analytics, Citations, PromptPerformance, QueryFanout } from './analytics';
+import { Opportunities } from './opportunities';
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { brandNameRule, domainsRule, nameRule } from './shared/rule';
+import { Tags } from './tags';
+import { callPromise, RestCallPromise } from '../internal/core/call-promise';
+import { callable } from '../internal/core/callable';
+import { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import { decoded, reviving } from '../internal/feature/validate';
+import { PagePromise, pages } from '../internal/page/page';
+import type {
+  BrandAnalytics,
+  BrandQueryFanout,
+  DateRange,
+  FanoutQuery,
+  GetBrandAnalyticsErrors,
+  GetBrandAnalyticsParams,
+  GetBrandAnalyticsResponses,
+  GetBrandQueryFanoutErrors,
+  GetBrandQueryFanoutParams,
+  GetBrandQueryFanoutResponses,
+  ListBrandPromptPerformanceErrors,
+  ListBrandPromptPerformanceParams,
+  ListBrandPromptPerformanceResponses,
+  ModelVisibility,
+  PromptPerformanceList,
+  ShareOfVoiceEntry,
+  ShareOfVoicePoint,
+  TagsFilter,
+  VisibilityPoint,
+} from '../types/analytics';
+import type {
+  Brand,
+  BrandsList,
+  CreateBrandErrors,
+  CreateBrandParams,
+  CreateBrandResponses,
+  GetBrandErrors,
+  GetBrandResponses,
+  ListBrandsErrors,
+  ListBrandsParams,
+  ListBrandsResponses,
+  UpdateBrandErrors,
+  UpdateBrandParams,
+  UpdateBrandResponses,
+} from '../types/brands';
+import type {
+  BrandOpportunities,
+  CitedPage,
+  GetBrandOpportunitiesErrors,
+  GetBrandOpportunitiesResponses,
+  Opportunity,
+  OpportunityPrompt,
+} from '../types/opportunities';
+import type { BrandIdPath } from '../types/shared/brand-id-path';
+import type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList } from '../types/tags';
+
+function reviveBrand(value: Brand): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('Brand.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+  if (value.updatedAt != null) {
+    value.updatedAt = decoded('Brand.updatedAt', value.updatedAt, (raw) => new Date(raw));
+  }
+}
+
+function reviveBrandsList(value: BrandsList): void {
+  if (value.data != null) {
+    value.data.forEach((item) => {
+      reviveBrand(item);
+    });
+  }
+  if (value.brands != null) {
+    value.brands.forEach((item) => {
+      reviveBrand(item);
+    });
+  }
+}
+
+export const listBrandsDescriptor = /* @__PURE__ */ callable({
+  address: '/brands',
+  auth: apiKeyRequirements,
+  method: 'get',
+  pagination: {
+    items: 'data',
+    limitParam: 'limit',
+    pages: 'pagination.totalPages',
+    param: 'page',
+    size: 'pagination.limit',
+    style: 'page',
+    total: 'pagination.total',
+  },
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveBrandsList) },
+} as const);
+
+export const createBrandDescriptor = /* @__PURE__ */ callable({
+  address: '/brands',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'post',
+  returns: 'json',
+  rules: [
+    {
+      min: 1,
+      name: 'id',
+      of: 'characters',
+    },
+    nameRule,
+    domainsRule,
+  ],
+  validators: { response: /* @__PURE__ */ reviving(reviveBrand) },
+} as const);
+
+export const getBrandFields = { path: ['brandId'] };
+
+export const getBrandDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveBrand) },
+} as const);
+
+export const updateBrandFields = { path: ['brandId'] };
+
+export const updateBrandDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'patch',
+  returns: 'json',
+  rules: [brandNameRule, domainsRule],
+  validators: { response: /* @__PURE__ */ reviving(reviveBrand) },
+} as const);
+
+/** Manage brand records */
+export class Brands extends ElmoResource {
+  /** Create a brand */
+  public create(
+    params: CreateBrandParams,
+    options?: RequestOptions,
+  ): RestCallPromise<CreateBrandResponses, CreateBrandErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      createBrandDescriptor,
+      mergeParams(groupParams(params, 'body'), options),
+    );
+  }
+
+  /**
+   * Get a brand
+   *
+   * @param brandId Brand identifier
+   */
+  public get(
+    brandId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<GetBrandResponses, GetBrandErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getBrandDescriptor,
+      mergeParams(placeParams({ brandId }, getBrandFields, 'query'), options),
+    );
+  }
+
+  public list(
+    params?: ListBrandsParams,
+    options?: RequestOptions,
+  ): PagePromise<Brand, BrandsList, ListBrandsErrors> {
+    return pages(
+      options?.client ?? this.client,
+      listBrandsDescriptor,
+      mergeParams(groupParams(params, 'query'), options),
+    );
+  }
+
+  /**
+   * Update a brand
+   *
+   * @param brandId Brand identifier
+   */
+  public update(
+    brandId: string,
+    params: UpdateBrandParams,
+    options?: RequestOptions,
+  ): RestCallPromise<UpdateBrandResponses, UpdateBrandErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      updateBrandDescriptor,
+      mergeParams(placeParams({ ...params, brandId }, updateBrandFields, 'body'), options),
+    );
+  }
+
+  private _analytics?: Analytics;
+  /** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+  get analytics(): Analytics {
+    return (this._analytics ??= new Analytics(this.client));
+  }
+
+  private _citations?: Citations;
+  get citations(): Citations {
+    return (this._citations ??= new Citations(this.client));
+  }
+
+  private _opportunities?: Opportunities;
+  /** Where a brand could win more citations, and why */
+  get opportunities(): Opportunities {
+    return (this._opportunities ??= new Opportunities(this.client));
+  }
+
+  private _promptPerformance?: PromptPerformance;
+  /** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+  get promptPerformance(): PromptPerformance {
+    return (this._promptPerformance ??= new PromptPerformance(this.client));
+  }
+
+  private _queryFanout?: QueryFanout;
+  /** Aggregated visibility, share of voice, citations, and query fan-out for a brand */
+  get queryFanout(): QueryFanout {
+    return (this._queryFanout ??= new QueryFanout(this.client));
+  }
+
+  private _tags?: Tags;
+  /** The tags in use on a brand's prompts */
+  get tags(): Tags {
+    return (this._tags ??= new Tags(this.client));
+  }
+}
+
+export declare namespace Brands {
+  export type {
+    Analytics,
+    Brand,
+    BrandAnalytics,
+    BrandIdPath,
+    BrandOpportunities,
+    BrandQueryFanout,
+    BrandsList,
+    Citations,
+    CitedPage,
+    CreateBrandErrors,
+    CreateBrandParams,
+    CreateBrandResponses,
+    DateRange,
+    FanoutQuery,
+    GetBrandAnalyticsErrors,
+    GetBrandAnalyticsParams,
+    GetBrandAnalyticsResponses,
+    GetBrandErrors,
+    GetBrandOpportunitiesErrors,
+    GetBrandOpportunitiesResponses,
+    GetBrandQueryFanoutErrors,
+    GetBrandQueryFanoutParams,
+    GetBrandQueryFanoutResponses,
+    GetBrandResponses,
+    ListBrandPromptPerformanceErrors,
+    ListBrandPromptPerformanceParams,
+    ListBrandPromptPerformanceResponses,
+    ListBrandsErrors,
+    ListBrandsParams,
+    ListBrandsResponses,
+    ListBrandTagsErrors,
+    ListBrandTagsResponses,
+    ModelVisibility,
+    Opportunities,
+    Opportunity,
+    OpportunityPrompt,
+    PromptPerformance,
+    PromptPerformanceList,
+    QueryFanout,
+    ShareOfVoiceEntry,
+    ShareOfVoicePoint,
+    Tag,
+    TagList,
+    Tags,
+    TagsFilter,
+    UpdateBrandErrors,
+    UpdateBrandParams,
+    UpdateBrandResponses,
+    VisibilityPoint,
+  };
+}