@elmohq/sdk 0.0.0-claim → 0.1.0

package/src/resources/prompts.ts

@@ -0,0 +1,292 @@
+import { Runs } from './runs';
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { valueRule } from './shared/rule';
+import { Snapshot } from './snapshots';
+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 {
+  CreatePromptErrors,
+  CreatePromptParams,
+  CreatePromptResponses,
+  DeletePromptErrors,
+  DeletePromptResponse,
+  DeletePromptResponses,
+  GetPromptErrors,
+  GetPromptResponses,
+  ListPromptsErrors,
+  ListPromptsParams,
+  ListPromptsResponse,
+  ListPromptsResponses,
+  Prompt,
+  UpdatePromptErrors,
+  UpdatePromptParams,
+  UpdatePromptResponses,
+} from '../types/prompts';
+import type {
+  GetRunErrors,
+  GetRunResponses,
+  ListPromptRunsErrors,
+  ListPromptRunsParams,
+  ListPromptRunsResponses,
+  Run,
+  RunCitation,
+  RunList,
+  RunSummary,
+} from '../types/runs';
+import type {
+  CitedURLEntry,
+  GetPromptSnapshotErrors,
+  GetPromptSnapshotParams,
+  GetPromptSnapshotResponses,
+  PromptSnapshot,
+} from '../types/snapshots';
+
+function revivePrompt(value: Prompt): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('Prompt.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+  if (value.updatedAt != null) {
+    value.updatedAt = decoded('Prompt.updatedAt', value.updatedAt, (raw) => new Date(raw));
+  }
+}
+
+export const listPromptsDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts',
+  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: (data: unknown) => {
+      const value = data as ListPromptsResponse;
+      if (value == null) {
+        return value;
+      }
+      if (value.data != null) {
+        value.data.forEach((item) => {
+          revivePrompt(item);
+        });
+      }
+      if (value.prompts != null) {
+        value.prompts.forEach((item) => {
+          revivePrompt(item);
+        });
+      }
+      return value;
+    },
+  },
+} as const);
+
+export const createPromptDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'post',
+  returns: 'json',
+  rules: [valueRule],
+  validators: { response: /* @__PURE__ */ reviving(revivePrompt) },
+} as const);
+
+export const deletePromptFields = { path: ['promptId'] };
+
+export const deletePromptDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}',
+  auth: apiKeyRequirements,
+  method: 'delete',
+  returns: 'json',
+  validators: {
+    response: (data: unknown) => {
+      const value = data as DeletePromptResponse;
+      if (value == null) {
+        return value;
+      }
+      if (value.createdAt != null) {
+        value.createdAt = decoded('createdAt', value.createdAt, (raw) => new Date(raw));
+      }
+      if (value.updatedAt != null) {
+        value.updatedAt = decoded('updatedAt', value.updatedAt, (raw) => new Date(raw));
+      }
+      return value;
+    },
+  },
+} as const);
+
+export const getPromptFields = { path: ['promptId'] };
+
+export const getPromptDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(revivePrompt) },
+} as const);
+
+export const updatePromptFields = { path: ['promptId'] };
+
+export const updatePromptDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'patch',
+  returns: 'json',
+  rules: [valueRule],
+  validators: { response: /* @__PURE__ */ reviving(revivePrompt) },
+} as const);
+
+/** Manage brand prompts */
+export class Prompts extends ElmoResource {
+  /**
+   * Create a new prompt
+   *
+   * Create a new prompt for a brand. This will automatically schedule the prompt for execution.
+   */
+  public create(
+    params: CreatePromptParams,
+    options?: RequestOptions,
+  ): RestCallPromise<CreatePromptResponses, CreatePromptErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      createPromptDescriptor,
+      mergeParams(groupParams(params, 'body'), options),
+    );
+  }
+
+  /**
+   * Delete a prompt
+   *
+   * Permanently delete a prompt and cancel all related scheduled jobs. This will also cascade
+   * delete all associated prompt runs.
+   *
+   * Requires an instance admin key; organization keys receive `403`. The dashboard has no delete
+   * either — stop tracking a prompt with `prompts.update()` and `enabled: false`, which keeps its
+   * history and frees the plan slot.
+   *
+   * @param promptId The ID of the prompt to delete
+   */
+  public delete(
+    promptId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<DeletePromptResponses, DeletePromptErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      deletePromptDescriptor,
+      mergeParams(placeParams({ promptId }, deletePromptFields, 'query'), options),
+    );
+  }
+
+  /**
+   * Get a prompt
+   *
+   * Retrieve a specific prompt by ID
+   *
+   * @param promptId The ID of the prompt
+   */
+  public get(
+    promptId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<GetPromptResponses, GetPromptErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getPromptDescriptor,
+      mergeParams(placeParams({ promptId }, getPromptFields, 'query'), options),
+    );
+  }
+
+  /**
+   * List all prompts
+   *
+   * Retrieve a paginated list of all prompts across all brands
+   */
+  public list(
+    params?: ListPromptsParams,
+    options?: RequestOptions,
+  ): PagePromise<Prompt, ListPromptsResponse, ListPromptsErrors> {
+    return pages(
+      options?.client ?? this.client,
+      listPromptsDescriptor,
+      mergeParams(groupParams(params, 'query'), options),
+    );
+  }
+
+  /**
+   * Update a prompt
+   *
+   * Update a prompt's properties. Only provided fields will be updated. Toggling `enabled`
+   * schedules or unschedules the recurring run job.
+   *
+   * @param promptId The ID of the prompt to update
+   */
+  public update(
+    promptId: string,
+    params: UpdatePromptParams,
+    options?: RequestOptions,
+  ): RestCallPromise<UpdatePromptResponses, UpdatePromptErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      updatePromptDescriptor,
+      mergeParams(placeParams({ ...params, promptId }, updatePromptFields, 'body'), options),
+    );
+  }
+
+  private _runs?: Runs;
+  /** Individual model answers behind the aggregates */
+  get runs(): Runs {
+    return (this._runs ??= new Runs(this.client));
+  }
+
+  private _snapshot?: Snapshot;
+  /** Aggregated analytics snapshots for prompts */
+  get snapshot(): Snapshot {
+    return (this._snapshot ??= new Snapshot(this.client));
+  }
+}
+
+export declare namespace Prompts {
+  export type {
+    CitedURLEntry,
+    CreatePromptErrors,
+    CreatePromptParams,
+    CreatePromptResponses,
+    DeletePromptErrors,
+    DeletePromptResponse,
+    DeletePromptResponses,
+    GetPromptErrors,
+    GetPromptResponses,
+    GetPromptSnapshotErrors,
+    GetPromptSnapshotParams,
+    GetPromptSnapshotResponses,
+    GetRunErrors,
+    GetRunResponses,
+    ListPromptRunsErrors,
+    ListPromptRunsParams,
+    ListPromptRunsResponses,
+    ListPromptsErrors,
+    ListPromptsParams,
+    ListPromptsResponse,
+    ListPromptsResponses,
+    Prompt,
+    PromptSnapshot,
+    Run,
+    RunCitation,
+    RunList,
+    Runs,
+    RunSummary,
+    Snapshot,
+    UpdatePromptErrors,
+    UpdatePromptParams,
+    UpdatePromptResponses,
+  };
+}

package/src/resources/reports.ts

@@ -0,0 +1,211 @@
+import { apiKeyRequirements } from './shared/auth';
+import type { RequestOptions } from './shared/request-options';
+import { ElmoResource } from './shared/resource';
+import { brandNameRule } from './shared/rule';
+import { callPromise, RestCallPromise } from '../internal/core/call-promise';
+import { callable } from '../internal/core/callable';
+import { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import { decoded } from '../internal/feature/validate';
+import { PagePromise, pages } from '../internal/page/page';
+import type {
+  CreateReportErrors,
+  CreateReportParams,
+  CreateReportResponse,
+  CreateReportResponses,
+  GetReportErrors,
+  GetReportParams,
+  GetReportResponse,
+  GetReportResponses,
+  ListReportsErrors,
+  ListReportsParams,
+  ListReportsResponse,
+  ListReportsResponses,
+  ReportPromptSnapshot,
+  ReportSummary,
+} from '../types/reports';
+
+function reviveReportSummary(value: ReportSummary): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('ReportSummary.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+  if (value.completedAt != null) {
+    value.completedAt = decoded(
+      'ReportSummary.completedAt',
+      value.completedAt,
+      (raw) => new Date(raw),
+    );
+  }
+}
+
+export const listReportsDescriptor = /* @__PURE__ */ callable({
+  address: '/reports',
+  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: (data: unknown) => {
+      const value = data as ListReportsResponse;
+      if (value == null) {
+        return value;
+      }
+      if (value.data != null) {
+        value.data.forEach((item) => {
+          reviveReportSummary(item);
+        });
+      }
+      if (value.reports != null) {
+        value.reports.forEach((item) => {
+          reviveReportSummary(item);
+        });
+      }
+      return value;
+    },
+  },
+} as const);
+
+export const createReportDescriptor = /* @__PURE__ */ callable({
+  address: '/reports',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'post',
+  returns: 'json',
+  rules: [
+    brandNameRule,
+    {
+      max: 10,
+      name: 'brandAliases',
+      of: 'items',
+    },
+    {
+      min: 1,
+      name: 'brandWebsite',
+      of: 'characters',
+    },
+  ],
+  validators: {
+    response: (data: unknown) => {
+      const value = data as CreateReportResponse;
+      if (value == null) {
+        return value;
+      }
+      if (value.createdAt != null) {
+        value.createdAt = decoded('createdAt', value.createdAt, (raw) => new Date(raw));
+      }
+      return value;
+    },
+  },
+} as const);
+
+export const getReportFields = { path: ['reportId'] };
+
+export const getReportDescriptor = /* @__PURE__ */ callable({
+  address: '/reports/{reportId}',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: {
+    response: (data: unknown) => {
+      const value = data as GetReportResponse;
+      if (value == null) {
+        return value;
+      }
+      if (value.createdAt != null) {
+        value.createdAt = decoded('createdAt', value.createdAt, (raw) => new Date(raw));
+      }
+      if (value.completedAt != null) {
+        value.completedAt = decoded('completedAt', value.completedAt, (raw) => new Date(raw));
+      }
+      return value;
+    },
+  },
+} as const);
+
+/** Generate and retrieve AI Share of Voice reports */
+export class Reports extends ElmoResource {
+  /**
+   * Create a report
+   *
+   * Create a new AI Share of Voice report and queue it for generation. The report will evaluate the
+   * brand across multiple AI engines (ChatGPT, Claude, Google AI) using generated and optional
+   * custom prompts.
+   *
+   * Requires an instance admin key; organization keys receive `403`.
+   */
+  public create(
+    params: CreateReportParams,
+    options?: RequestOptions,
+  ): RestCallPromise<CreateReportResponses, CreateReportErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      createReportDescriptor,
+      mergeParams(groupParams(params, 'body'), options),
+    );
+  }
+
+  /**
+   * Get report status and data
+   *
+   * Poll a report's status. When completed, returns per-prompt snapshot data with raw mention
+   * counts. Consumers are responsible for computing SoV and other derived metrics from the raw
+   * data.
+   *
+   * Requires an instance admin key; organization keys receive `403`.
+   *
+   * @param reportId The ID of the report
+   */
+  public get(
+    reportId: string,
+    params?: GetReportParams,
+    options?: RequestOptions,
+  ): RestCallPromise<GetReportResponses, GetReportErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getReportDescriptor,
+      mergeParams(placeParams({ ...params, reportId }, getReportFields, 'query'), options),
+    );
+  }
+
+  /**
+   * Retrieve a paginated list of all reports, ordered by creation date (newest first).
+   *
+   * Requires an instance admin key; organization keys receive `403`.
+   */
+  public list(
+    params?: ListReportsParams,
+    options?: RequestOptions,
+  ): PagePromise<ReportSummary, ListReportsResponse, ListReportsErrors> {
+    return pages(
+      options?.client ?? this.client,
+      listReportsDescriptor,
+      mergeParams(groupParams(params, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Reports {
+  export type {
+    CreateReportErrors,
+    CreateReportParams,
+    CreateReportResponse,
+    CreateReportResponses,
+    GetReportErrors,
+    GetReportParams,
+    GetReportResponse,
+    GetReportResponses,
+    ListReportsErrors,
+    ListReportsParams,
+    ListReportsResponse,
+    ListReportsResponses,
+    ReportPromptSnapshot,
+    ReportSummary,
+  };
+}

package/src/resources/runs.ts

@@ -0,0 +1,123 @@
+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 { PagePromise, pages } from '../internal/page/page';
+import type {
+  GetRunErrors,
+  GetRunResponses,
+  ListPromptRunsErrors,
+  ListPromptRunsParams,
+  ListPromptRunsResponses,
+  Run,
+  RunCitation,
+  RunList,
+  RunSummary,
+} from '../types/runs';
+
+export const listPromptRunsFields = { path: ['promptId'] };
+
+function reviveRunSummary(value: RunSummary): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('RunSummary.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+}
+
+function reviveRunList(value: RunList): void {
+  if (value.data != null) {
+    value.data.forEach((item) => {
+      reviveRunSummary(item);
+    });
+  }
+}
+
+export const listPromptRunsDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}/runs',
+  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(reviveRunList) },
+} as const);
+
+export const getRunFields = { path: ['promptId', 'runId'] };
+
+function reviveRun(value: Run): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('Run.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+}
+
+export const getRunDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}/runs/{runId}',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveRun) },
+} as const);
+
+/** Individual model answers behind the aggregates */
+export class Runs extends ElmoResource {
+  /**
+   * Get a run
+   *
+   * One model answer, with its text normalized out of the provider’s response and its citations in
+   * the order the engine listed them. A run belonging to some other prompt answers `404`. The
+   * provider’s raw payload is deliberately not exposed — its shape belongs to the provider, not to
+   * this API.
+   */
+  public get(
+    promptId: string,
+    runId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<GetRunResponses, GetRunErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getRunDescriptor,
+      mergeParams(placeParams({ promptId, runId }, getRunFields, 'query'), options),
+    );
+  }
+
+  /**
+   * List runs for a prompt
+   *
+   * Individual model answers behind the aggregates, newest first, without their text — the list
+   * stays small enough to page through. Fetch `prompts.runs.get()` for the answer itself.
+   */
+  public list(
+    promptId: string,
+    params: ListPromptRunsParams,
+    options?: RequestOptions,
+  ): PagePromise<RunSummary, RunList, ListPromptRunsErrors> {
+    return pages(
+      options?.client ?? this.client,
+      listPromptRunsDescriptor,
+      mergeParams(placeParams({ ...params, promptId }, listPromptRunsFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Runs {
+  export type {
+    GetRunErrors,
+    GetRunResponses,
+    ListPromptRunsErrors,
+    ListPromptRunsParams,
+    ListPromptRunsResponses,
+    Run,
+    RunCitation,
+    RunList,
+    RunSummary,
+  };
+}

package/src/resources/shared/auth.ts

@@ -0,0 +1,13 @@
+import type { AuthScheme } from '../../internal/core/types';
+
+/**
+ * An instance admin key from `ADMIN_API_KEYS`, or an organization key (`elmo_…`) issued from the
+ * dashboard.
+ */
+export const apiKeyRequirements = [
+  {
+    key: 'apiKey',
+    scheme: 'bearer',
+    type: 'http',
+  },
+] as const satisfies ReadonlyArray<AuthScheme>;

package/src/resources/shared/request-options.ts

@@ -0,0 +1,26 @@
+import type { BaseURL, BehaviorOptions, ClientCredentials } from '../../client';
+import type { Client } from '../../internal/core/client';
+import type {
+  AuthValue,
+  BodySerializerOptions,
+  ConnectionOptions,
+  MetadataOptions,
+  PageOptions,
+  SignalOptions,
+} from '../../internal/core/types';
+
+/** What one call may set for itself, overriding the client it goes through. */
+export type RequestOptions = BehaviorOptions &
+  BodySerializerOptions &
+  ClientCredentials &
+  ConnectionOptions<BaseURL, AuthValue, never> &
+  MetadataOptions &
+  PageOptions &
+  SignalOptions & {
+    /**
+     * The client that sends this call, in place of the one this SDK uses.
+     *
+     * Build one with `createElmoClient`.
+     */
+    client?: Client;
+  };

package/src/resources/shared/resource.ts

@@ -0,0 +1,23 @@
+import type { ClientOptions } from '../../client';
+import type { Client } from '../../internal/core/client';
+import { clientFor, withClient } from '../../internal/core/client';
+
+export class ElmoResource {
+  /** The client every call on this SDK dispatches through. */
+  readonly client: Client;
+
+  constructor(client: Client) {
+    this.client = client;
+  }
+
+  /**
+   * The same calls, with different options.
+   *
+   * Options given here layer over the ones already in force. Headers, path
+   * parameters and query parameters merge per name. Everything else replaces.
+   * What this was called on does not change.
+   */
+  public withOptions(options: ClientOptions): this {
+    return withClient(this, clientFor(options, this.client));
+  }
+}