@elmohq/sdk 0.0.0-stage → 0.1.1

package/src/internal/feature/timeout.ts

@@ -0,0 +1,146 @@
+import { TIMER_LIMIT } from '../core/backoff';
+import { replyWith } from '../core/body';
+import { calledOffWith, safeAddress, TimeoutError } from '../core/errors';
+import type {
+  CallableDescriptor,
+  CallTimeout,
+  Feature,
+  PreparedRequest,
+  Result,
+  Send,
+} from '../core/types';
+
+/**
+ * Chooses the limit of one call, given the operation as `METHOD /path` and the
+ * limit it would otherwise get. `undefined` keeps that limit.
+ */
+export type TimeoutPolicy = (operation: string, timeout: CallTimeout) => CallTimeout | undefined;
+
+/** A limit in milliseconds, `false` for none, or a policy choosing one per call. */
+export type TimeoutValue = CallTimeout | TimeoutPolicy;
+
+export interface TimeoutOptions {
+  ms?: number;
+}
+
+function describeTarget(request: PreparedRequest): string | undefined {
+  const { method } = request.callable;
+  if (typeof request.address !== 'string') return undefined;
+  const address = safeAddress(request.address);
+  return method ? `${method.toUpperCase()} "${address}"` : `"${address}"`;
+}
+
+export const DEFAULT_TIMEOUT = 60_000;
+
+function operationKey({ address, method }: CallableDescriptor): string {
+  return method ? `${method.toUpperCase()} ${address}` : address;
+}
+
+export function resolveTimeout(base: TimeoutOptions, request: PreparedRequest): number | undefined {
+  const own = request.callable.timeout ?? base.ms ?? DEFAULT_TIMEOUT;
+  const option = request.options['timeout'] as TimeoutValue | undefined;
+  const ms =
+    typeof option === 'function'
+      ? (option(operationKey(request.callable), own) ?? own)
+      : (option ?? own);
+  if (ms === false) return undefined;
+  return ms > 0 && Number.isFinite(ms) ? ms : undefined;
+}
+
+function watchedReply(
+  response: Response,
+  wait: <T>(pending: Promise<T>) => Promise<T>,
+  done: () => void,
+): Response {
+  const reader = response.body!.getReader();
+  const body = new ReadableStream<Uint8Array>({
+    cancel(reason) {
+      done();
+      return reader.cancel(reason);
+    },
+    async pull(controller) {
+      const step = await wait(reader.read()).catch((error: unknown) => {
+        done();
+        reader.cancel(error).catch(done);
+        throw error;
+      });
+      if (step.done) {
+        done();
+        controller.close();
+      } else {
+        controller.enqueue(step.value);
+      }
+    },
+  });
+  return replyWith(body, response);
+}
+
+export function timeoutFeature(options: TimeoutOptions = {}): Feature {
+  async function bounded(request: PreparedRequest, next: Send, stream: boolean): Promise<Result> {
+    const ms = resolveTimeout(options, request);
+    if (ms === undefined) return next(request);
+    const delay = Math.min(ms, TIMER_LIMIT);
+    let left = delay;
+
+    const caller = request.signal;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    function abortWithCaller(): void {
+      controller.abort(caller?.reason);
+    }
+
+    if (caller?.aborted) abortWithCaller();
+    caller?.addEventListener('abort', abortWithCaller, { once: true });
+
+    const abandoned = new Promise<never>((_, reject) => {
+      function giveUp(): void {
+        reject(calledOffWith(signal.reason));
+      }
+      if (signal.aborted) giveUp();
+      else signal.addEventListener('abort', giveUp, { once: true });
+    });
+    abandoned.catch(() => {});
+
+    function expire(): void {
+      controller.abort(new TimeoutError(ms, undefined, describeTarget(request)));
+    }
+
+    async function wait<T>(pending: Promise<T>): Promise<T> {
+      const started = Date.now();
+      const timer = setTimeout(expire, left);
+      try {
+        return await Promise.race([pending, abandoned]);
+      } finally {
+        clearTimeout(timer);
+        left = stream ? delay : left - (Date.now() - started);
+      }
+    }
+
+    function done(): void {
+      caller?.removeEventListener('abort', abortWithCaller);
+    }
+
+    request.signal = signal;
+    const result = await wait(next(request))
+      .catch((error: unknown) => {
+        done();
+        throw error;
+      })
+      .finally(() => {
+        request.signal = caller;
+      });
+    const { response } = result;
+    if (response?.body && stream) {
+      return { ...result, response: watchedReply(response, wait, done) };
+    }
+    done();
+    return result;
+  }
+
+  return {
+    name: 'timeout',
+    onOpen: (request, next) => bounded(request, next, true),
+    onSend: (request, next) => bounded(request, next, !!request.options.unread),
+  };
+}

package/src/internal/feature/validate.ts

@@ -0,0 +1,82 @@
+import { unreadableValue } from '../core/errors';
+import { readReply } from '../core/read-reply';
+import type { CallableDescriptor, Feature, ResolvedOptions } from '../core/types';
+
+export type Validate<TIn = unknown, TOut = TIn> = (value: TIn) => Promise<TOut> | TOut;
+
+export async function runValidator<T>(
+  validate: Validate<T, T> | undefined,
+  value: T,
+  options: ResolvedOptions,
+  response?: Response,
+): Promise<T> {
+  if (!validate || options['validate'] === false) return value;
+  return await readReply(validate, value, response);
+}
+
+export interface CallableValidators {
+  error?: Validate;
+  request?: Validate<ResolvedOptions, Partial<ResolvedOptions>>;
+  response?: Validate;
+}
+
+export function validatorsOf(callable: CallableDescriptor): CallableValidators | undefined {
+  return callable.validators as CallableValidators | undefined;
+}
+
+export function validateFeature(): Feature {
+  return {
+    name: 'validate',
+    async onOptions(options, callable) {
+      const validate = validatorsOf(callable)?.request;
+      if (!validate || options['validate'] === false) return;
+      Object.assign(options, await validate(options));
+    },
+    async onResult(result, request) {
+      const validators = validatorsOf(request.callable);
+      if (!validators) return result;
+      if (result.error !== undefined && result.error !== null) {
+        result.error = await runValidator(
+          validators.error,
+          result.error,
+          request.options,
+          result.response,
+        );
+      } else if (result.data !== undefined) {
+        result.data = await runValidator(
+          validators.response,
+          result.data,
+          request.options,
+          result.response,
+        );
+      }
+      return result;
+    },
+  };
+}
+
+export function decoded<TIn, TOut>(at: string, value: TIn, read: (value: TIn) => TOut): TOut {
+  let result: TOut;
+  try {
+    result = read(value);
+  } catch (cause) {
+    throw unreadableValue(at, value, cause);
+  }
+  if (result instanceof Date && Number.isNaN(result.getTime())) throw unreadableValue(at, value);
+  return result;
+}
+
+export type Mutable<T> = T extends (...args: Array<never>) => unknown
+  ? T
+  : T extends object
+    ? {
+        -readonly [K in keyof T]: Mutable<T[K]>;
+      }
+    : T;
+
+export function reviving<T>(revive: (value: T) => void): Validate {
+  return (data) => {
+    if (data != null) revive(data as T);
+    return data;
+  };
+}

package/src/internal/transport/fetch.ts

@@ -0,0 +1,82 @@
+import { isStreamed } from '../core/body';
+import { safeAddress, unsendableAddress } from '../core/errors';
+import { metadataHeaders } from '../core/metadata';
+import type { PreparedRequest, Transport } from '../core/types';
+
+/** A `fetch` function, called with the full address and a built `RequestInit`. */
+export type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+
+/** What `fetch` takes, less what the client sets itself. */
+export interface FetchOptions extends RequestInit {
+  /** Set by the client. */
+  body?: never;
+  /** Set by the client. Pass `headers` to the call. */
+  headers?: never;
+  /** Set by the client. */
+  method?: never;
+  /** Set by the client. Pass `signal` to the call. */
+  signal?: never;
+}
+
+function checkAddress(address: string): void {
+  let url: URL;
+  try {
+    url = new URL(address, (globalThis as { location?: { href: string } }).location?.href);
+  } catch {
+    throw unsendableAddress(
+      safeAddress(address),
+      'is not a full address',
+      'Start the base URL with `https://`.',
+    );
+  }
+  const shown = `${url.protocol}//${url.host}${url.pathname}`;
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw unsendableAddress(
+      shown,
+      `uses \`${url.protocol}\`, which fetch does not send`,
+      'Start the base URL with `https://`.',
+    );
+  }
+  if (url.username || url.password) {
+    throw unsendableAddress(
+      shown,
+      'holds a user name or password, which fetch refuses',
+      'Pass the credential as an option instead.',
+    );
+  }
+}
+
+const OWNED = ['body', 'headers', 'method', 'signal'] as const;
+
+function extraInit(request: PreparedRequest<string>): RequestInit | undefined {
+  const extra = request.options['fetchOptions'] as RequestInit | undefined;
+  if (!extra) return undefined;
+  const rest: RequestInit = { ...extra };
+  for (const key of OWNED) delete rest[key];
+  return rest;
+}
+
+function toRequestInit(request: PreparedRequest<string>): RequestInit {
+  return {
+    ...extraInit(request),
+    ...(request.body !== undefined && { body: request.body }),
+    ...(isStreamed(request.body) && { duplex: 'half' }),
+    headers: metadataHeaders(request.meta),
+    method: (request.callable.method ?? 'get').toUpperCase(),
+    ...(request.signal !== undefined && { signal: request.signal }),
+  };
+}
+
+export function createFetchTransport(fetchFn?: Fetch): Transport<string, 'unary'> {
+  function send(request: PreparedRequest<string>): Promise<Response> {
+    const configured = request.options['fetch'] as Fetch | undefined;
+    const call = configured ?? fetchFn ?? globalThis.fetch;
+    if (call === globalThis.fetch) checkAddress(request.address);
+    return call(request.address, toRequestInit(request));
+  }
+
+  return {
+    name: 'fetch',
+    unary: send,
+  };
+}

package/src/resources/analytics.ts

@@ -0,0 +1,364 @@
+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 {
+  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: Mutable<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: Mutable<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: Mutable<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: Mutable<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: Mutable<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: Mutable<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: Mutable<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,
+  };
+}