@elmohq/sdk 0.0.0-stage → 0.1.1

package/src/resources/runs.ts

@@ -0,0 +1,124 @@
+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 { PagePromise, pages } from '../internal/core/page';
+import { mergeParams, placeParams } from '../internal/core/params';
+import type { Mutable } from '../internal/feature/validate';
+import { decoded, reviving } from '../internal/feature/validate';
+import type {
+  GetRunErrors,
+  GetRunResponses,
+  ListPromptRunsErrors,
+  ListPromptRunsParams,
+  ListPromptRunsResponses,
+  Run,
+  RunCitation,
+  RunList,
+  RunSummary,
+} from '../types/runs';
+
+export const listPromptRunsFields = { path: ['promptId'] };
+
+function reviveRunSummary(value: Mutable<RunSummary>): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('RunSummary.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+}
+
+function reviveRunList(value: Mutable<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: Mutable<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));
+  }
+}

package/src/resources/shared/rule.ts

@@ -0,0 +1,25 @@
+import type { InputRule } from '../../internal/core/types';
+
+export const nameRule: InputRule = {
+  min: 1,
+  name: 'name',
+  of: 'characters',
+};
+
+export const domainsRule: InputRule = {
+  min: 1,
+  name: 'domains',
+  of: 'items',
+};
+
+export const brandNameRule: InputRule = {
+  min: 1,
+  name: 'brandName',
+  of: 'characters',
+};
+
+export const valueRule: InputRule = {
+  min: 1,
+  name: 'value',
+  of: 'characters',
+};

package/src/resources/snapshots.ts

@@ -0,0 +1,54 @@
+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 {
+  CitedURLEntry,
+  GetPromptSnapshotErrors,
+  GetPromptSnapshotParams,
+  GetPromptSnapshotResponses,
+  PromptSnapshot,
+} from '../types/snapshots';
+
+export const getPromptSnapshotFields = { path: ['promptId'] };
+
+export const getPromptSnapshotDescriptor = /* @__PURE__ */ callable({
+  address: '/prompts/{promptId}/snapshot',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+} as const);
+
+/** Aggregated analytics snapshots for prompts */
+export class Snapshot extends ElmoResource {
+  /**
+   * Get an aggregated snapshot of mention and citation analytics for a specific prompt over a date
+   * range. Use this to identify competitive gaps, track brand visibility trends, and discover top
+   * cited URLs.
+   *
+   * @param promptId The ID of the prompt
+   */
+  public get(
+    promptId: string,
+    params: GetPromptSnapshotParams,
+    options?: RequestOptions,
+  ): RestCallPromise<GetPromptSnapshotResponses, GetPromptSnapshotErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getPromptSnapshotDescriptor,
+      mergeParams(placeParams({ ...params, promptId }, getPromptSnapshotFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Snapshot {
+  export type {
+    CitedURLEntry,
+    GetPromptSnapshotErrors,
+    GetPromptSnapshotParams,
+    GetPromptSnapshotResponses,
+    PromptSnapshot,
+  };
+}

package/src/resources/tags.ts

@@ -0,0 +1,46 @@
+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 { BrandIdPath } from '../types/shared/brand-id-path';
+import type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList } from '../types/tags';
+
+export const listBrandTagsFields = { path: ['brandId'] };
+
+export const listBrandTagsDescriptor = /* @__PURE__ */ callable({
+  address: '/brands/{brandId}/tags',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+} as const);
+
+/** The tags in use on a brand's prompts */
+export class Tags extends ElmoResource {
+  /**
+   * List a brand's tags
+   *
+   * Every tag in use on the brand's prompts, with how many carry each — enough to build the same
+   * filter the dashboard shows without paging the whole prompt list to derive it.
+   *
+   * Tags are not a resource of their own: a tag exists exactly as long as some prompt carries it.
+   * `branded` and `unbranded` are computed by Elmo and always listed.
+   *
+   * @param brandId Brand identifier.
+   */
+  public list(
+    brandId: BrandIdPath,
+    options?: RequestOptions,
+  ): RestCallPromise<ListBrandTagsResponses, ListBrandTagsErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      listBrandTagsDescriptor,
+      mergeParams(placeParams({ brandId }, listBrandTagsFields, 'query'), options),
+    );
+  }
+}
+
+export declare namespace Tags {
+  export type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList };
+}

package/src/resources/tools.ts

@@ -0,0 +1,69 @@
+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 { groupParams, mergeParams } from '../internal/core/params';
+import type {
+  AnalyzeBrandErrors,
+  AnalyzeBrandParams,
+  AnalyzeBrandResponses,
+  OnboardingSuggestion,
+} from '../types/tools';
+
+export const analyzeBrandDescriptor = /* @__PURE__ */ callable({
+  address: '/tools/analyze',
+  auth: apiKeyRequirements,
+  mediaType: 'application/json',
+  method: 'post',
+  returns: 'json',
+  rules: [
+    {
+      min: 1,
+      name: 'website',
+      of: 'characters',
+    },
+    {
+      max: 100,
+      min: 0,
+      name: 'maxCompetitors',
+    },
+    {
+      max: 100,
+      min: 0,
+      name: 'maxPrompts',
+    },
+  ],
+  timeout: 600000,
+} as const);
+
+/** One-shot helpers (e.g. brand analysis) that don't persist anything */
+export class Tools extends ElmoResource {
+  /**
+   * Analyze a website
+   *
+   * Run brand analysis without persisting anything. Returns suggested additional domains, aliases,
+   * competitors, and prompts.
+   *
+   * Requires an instance admin key; organization keys receive `403`.
+   */
+  public analyze(
+    params: AnalyzeBrandParams,
+    options?: RequestOptions,
+  ): RestCallPromise<AnalyzeBrandResponses, AnalyzeBrandErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      analyzeBrandDescriptor,
+      mergeParams(groupParams(params, 'body'), options),
+    );
+  }
+}
+
+export declare namespace Tools {
+  export type {
+    AnalyzeBrandErrors,
+    AnalyzeBrandParams,
+    AnalyzeBrandResponses,
+    OnboardingSuggestion,
+  };
+}