@elmohq/sdk 0.0.0-stage → 0.1.1

package/src/resources/brands.ts

@@ -0,0 +1,288 @@
+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 { PagePromise, pages } from '../internal/core/page';
+import { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import type { Mutable } from '../internal/feature/validate';
+import { decoded, reviving } from '../internal/feature/validate';
+import type {
+  BrandAnalytics,
+  BrandQueryFanout,
+  DateRange,
+  FanoutQuery,
+  GetBrandAnalyticsErrors,
+  GetBrandAnalyticsParams,
+  GetBrandAnalyticsResponses,
+  GetBrandQueryFanoutErrors,
+  GetBrandQueryFanoutParams,
+  GetBrandQueryFanoutResponses,
+  ListBrandPromptPerformanceErrors,
+  ListBrandPromptPerformanceParams,
+  ListBrandPromptPerformanceResponses,
+  ModelVisibility,
+  PromptPerformanceList,
+  PromptPerformance as PromptPerformanceSchema,
+  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: Mutable<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: Mutable<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,
+    PromptPerformanceSchema as PromptPerformance,
+    PromptPerformanceList,
+    PromptPerformance as PromptPerformanceResource,
+    QueryFanout,
+    ShareOfVoiceEntry,
+    ShareOfVoicePoint,
+    Tag,
+    TagList,
+    Tags,
+    TagsFilter,
+    UpdateBrandErrors,
+    UpdateBrandParams,
+    UpdateBrandResponses,
+    VisibilityPoint,
+  };
+}

package/src/resources/competitors.ts

@@ -0,0 +1,213 @@
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { nameRule } from './shared/rule';
+import { callPromise, RestCallPromise } from '../internal/core/call-promise';
+import { callable } from '../internal/core/callable';
+import { PagePromise, pages } from '../internal/core/page';
+import { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import type { Mutable } from '../internal/feature/validate';
+import { decoded, reviving } from '../internal/feature/validate';
+import type {
+  Competitor,
+  CompetitorsList,
+  CreateCompetitorErrors,
+  CreateCompetitorParams,
+  CreateCompetitorResponses,
+  DeleteCompetitorErrors,
+  DeleteCompetitorResponses,
+  GetCompetitorErrors,
+  GetCompetitorResponses,
+  ListCompetitorsErrors,
+  ListCompetitorsParams,
+  ListCompetitorsResponses,
+  UpdateCompetitorErrors,
+  UpdateCompetitorParams,
+  UpdateCompetitorResponses,
+} from '../types/competitors';
+
+function reviveCompetitor(value: Mutable<Competitor>): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('Competitor.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+  if (value.updatedAt != null) {
+    value.updatedAt = decoded('Competitor.updatedAt', value.updatedAt, (raw) => new Date(raw));
+  }
+}
+
+function reviveCompetitorsList(value: Mutable<CompetitorsList>): void {
+  if (value.data != null) {
+    value.data.forEach((item) => {
+      reviveCompetitor(item);
+    });
+  }
+  if (value.competitors != null) {
+    value.competitors.forEach((item) => {
+      reviveCompetitor(item);
+    });
+  }
+}
+
+export const listCompetitorsDescriptor = /* @__PURE__ */ callable({
+  address: '/competitors',
+  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(reviveCompetitorsList) },
+} as const);
+
+export const createCompetitorDescriptor = /* @__PURE__ */ callable({
+  address: '/competitors',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'post',
+  returns: 'json',
+  rules: [
+    {
+      min: 1,
+      name: 'brandId',
+      of: 'characters',
+    },
+    nameRule,
+  ],
+  validators: { response: /* @__PURE__ */ reviving(reviveCompetitor) },
+} as const);
+
+export const deleteCompetitorFields = { path: ['competitorId'] };
+
+export const deleteCompetitorDescriptor = /* @__PURE__ */ callable({
+  address: '/competitors/{competitorId}',
+  auth: apiKeyRequirements,
+  method: 'delete',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveCompetitor) },
+} as const);
+
+export const getCompetitorFields = { path: ['competitorId'] };
+
+export const getCompetitorDescriptor = /* @__PURE__ */ callable({
+  address: '/competitors/{competitorId}',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveCompetitor) },
+} as const);
+
+export const updateCompetitorFields = { path: ['competitorId'] };
+
+export const updateCompetitorDescriptor = /* @__PURE__ */ callable({
+  address: '/competitors/{competitorId}',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'patch',
+  returns: 'json',
+  rules: [nameRule],
+  validators: { response: /* @__PURE__ */ reviving(reviveCompetitor) },
+} as const);
+
+/** Manage brand competitors */
+export class Competitors extends ElmoResource {
+  /** Add a competitor */
+  public create(
+    params: CreateCompetitorParams,
+    options?: RequestOptions,
+  ): RestCallPromise<CreateCompetitorResponses, CreateCompetitorErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      createCompetitorDescriptor,
+      mergeParams(groupParams(params, 'body'), options),
+    );
+  }
+
+  /**
+   * Delete a competitor
+   *
+   * @param competitorId Competitor identifier (UUID)
+   */
+  public delete(
+    competitorId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<DeleteCompetitorResponses, DeleteCompetitorErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      deleteCompetitorDescriptor,
+      mergeParams(placeParams({ competitorId }, deleteCompetitorFields, 'query'), options),
+    );
+  }
+
+  /**
+   * Get a competitor
+   *
+   * @param competitorId Competitor identifier (UUID)
+   */
+  public get(
+    competitorId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<GetCompetitorResponses, GetCompetitorErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getCompetitorDescriptor,
+      mergeParams(placeParams({ competitorId }, getCompetitorFields, 'query'), options),
+    );
+  }
+
+  public list(
+    params?: ListCompetitorsParams,
+    options?: RequestOptions,
+  ): PagePromise<Competitor, CompetitorsList, ListCompetitorsErrors> {
+    return pages(
+      options?.client ?? this.client,
+      listCompetitorsDescriptor,
+      mergeParams(groupParams(params, 'query'), options),
+    );
+  }
+
+  /**
+   * Update a competitor
+   *
+   * @param competitorId Competitor identifier (UUID)
+   */
+  public update(
+    competitorId: string,
+    params: UpdateCompetitorParams,
+    options?: RequestOptions,
+  ): RestCallPromise<UpdateCompetitorResponses, UpdateCompetitorErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      updateCompetitorDescriptor,
+      mergeParams(
+        placeParams({ ...params, competitorId }, updateCompetitorFields, 'body'),
+        options,
+      ),
+    );
+  }
+}
+
+export declare namespace Competitors {
+  export type {
+    Competitor,
+    CompetitorsList,
+    CreateCompetitorErrors,
+    CreateCompetitorParams,
+    CreateCompetitorResponses,
+    DeleteCompetitorErrors,
+    DeleteCompetitorResponses,
+    GetCompetitorErrors,
+    GetCompetitorResponses,
+    ListCompetitorsErrors,
+    ListCompetitorsParams,
+    ListCompetitorsResponses,
+    UpdateCompetitorErrors,
+    UpdateCompetitorParams,
+    UpdateCompetitorResponses,
+  };
+}

package/src/resources/identity.ts

@@ -0,0 +1,49 @@
+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 type { Mutable } from '../internal/feature/validate';
+import { decoded, reviving } from '../internal/feature/validate';
+import type { APIKeyIdentity, GetMeErrors, GetMeResponses } from '../types/identity';
+
+function reviveApiKeyIdentity(value: Mutable<APIKeyIdentity>): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('ApiKeyIdentity.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+  if (value.expiresAt != null) {
+    value.expiresAt = decoded('ApiKeyIdentity.expiresAt', value.expiresAt, (raw) => new Date(raw));
+  }
+  if (value.lastUsedAt != null) {
+    value.lastUsedAt = decoded(
+      'ApiKeyIdentity.lastUsedAt',
+      value.lastUsedAt,
+      (raw) => new Date(raw),
+    );
+  }
+}
+
+export const getMeDescriptor = /* @__PURE__ */ callable({
+  address: '/me',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveApiKeyIdentity) },
+} as const);
+
+/** What the calling key is and what it may reach */
+export class Me extends ElmoResource {
+  /**
+   * Describe the calling key
+   *
+   * What this key is, which organization and brands it reaches, and which scopes it holds. Requires
+   * no scope, so it is always safe to call first when wiring up an integration.
+   */
+  public get(options?: RequestOptions): RestCallPromise<GetMeResponses, GetMeErrors> {
+    return callPromise(options?.client ?? this.client, getMeDescriptor, options);
+  }
+}
+
+export declare namespace Me {
+  export type { APIKeyIdentity, GetMeErrors, GetMeResponses };
+}

package/src/resources/models.ts

@@ -0,0 +1,32 @@
+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 type { ListModelsErrors, ListModelsResponses, Model, ModelList } from '../types/models';
+
+export const listModelsDescriptor = /* @__PURE__ */ callable({
+  address: '/models',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+} as const);
+
+/** The answer engines this deployment can track */
+export class Models extends ElmoResource {
+  /**
+   * List trackable models
+   *
+   * The answer engines this deployment can track, so a client can build a model filter without
+   * hardcoding ids that differ between deployments.
+   *
+   * Requires no scope.
+   */
+  public list(options?: RequestOptions): RestCallPromise<ListModelsResponses, ListModelsErrors> {
+    return callPromise(options?.client ?? this.client, listModelsDescriptor, options);
+  }
+}
+
+export declare namespace Models {
+  export type { ListModelsErrors, ListModelsResponses, Model, ModelList };
+}

package/src/resources/opportunities.ts

@@ -0,0 +1,81 @@
+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 type { Mutable } from '../internal/feature/validate';
+import { decoded, reviving } from '../internal/feature/validate';
+import type {
+  BrandOpportunities,
+  CitedPage,
+  GetBrandOpportunitiesErrors,
+  GetBrandOpportunitiesResponses,
+  Opportunity,
+  OpportunityPrompt,
+} from '../types/opportunities';
+import type { BrandIdPath } from '../types/shared/brand-id-path';
+
+export const getBrandOpportunitiesFields = { path: ['brandId'] };
+
+function reviveBrandOpportunities(value: Mutable<BrandOpportunities>): void {
+  if (value.generatedAt != null) {
+    value.generatedAt = decoded(
+      'BrandOpportunities.generatedAt',
+      value.generatedAt,
+      (raw) => new Date(raw),
+    );
+  }
+}
+
+export const getBrandOpportunitiesDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/opportunities',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  timeout: 600000,
+  validators: { response: /* @__PURE__ */ reviving(reviveBrandOpportunities) },
+} as const);
+
+/** Where a brand could win more citations, and why */
+export class Opportunities extends ElmoResource {
+  /**
+   * Get the latest opportunities report
+   *
+   * **Experimental — the response shape may still change.**
+   *
+   * The brand's Opportunities report: a prioritized set of ways to get cited more often, with the
+   * tracked prompts and cited pages behind each one. The same analysis the dashboard shows, from
+   * the same code.
+   *
+   * Generation is inline and synchronous. A stored report is served while it is fresh and
+   * regenerated when it is not, so there is nothing to poll for and no way to be handed a stale one
+   * — but a request that triggers a generation waits for it. The freshness window bounds the cost:
+   * however many callers ask, one generation per brand per window. There is deliberately no `POST`,
+   * which would spend provider budget with nothing metering it per call.
+   *
+   * @experimental
+   * @param brandId Brand identifier.
+   */
+  public get(
+    brandId: BrandIdPath,
+    options?: RequestOptions,
+  ): RestCallPromise<GetBrandOpportunitiesResponses, GetBrandOpportunitiesErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getBrandOpportunitiesDescriptor,
+      mergeParams(placeParams({ brandId }, getBrandOpportunitiesFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Opportunities {
+  export type {
+    BrandOpportunities,
+    CitedPage,
+    GetBrandOpportunitiesErrors,
+    GetBrandOpportunitiesResponses,
+    Opportunity,
+    OpportunityPrompt,
+  };
+}