@elmohq/sdk 0.0.0-stage → 0.1.1

package/src/resources/organizations.ts

@@ -0,0 +1,182 @@
+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 { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import type { Mutable } from '../internal/feature/validate';
+import { decoded, reviving } from '../internal/feature/validate';
+import type {
+  BillingPlan,
+  GetOrganizationBillingErrors,
+  GetOrganizationBillingResponses,
+  GetOrganizationErrors,
+  GetOrganizationResponses,
+  ListOrganizationsErrors,
+  ListOrganizationsParams,
+  ListOrganizationsResponses,
+  Organization,
+  OrganizationBilling,
+  OrganizationList,
+  PlanLimits,
+} from '../types/organizations';
+
+export const getOrganizationBillingFields = { path: ['organizationId'] };
+
+function reviveBillingPlan(value: Mutable<BillingPlan>): void {
+  if (value.periodEnd != null) {
+    value.periodEnd = decoded('BillingPlan.periodEnd', value.periodEnd, (raw) => new Date(raw));
+  }
+}
+
+function reviveOrganizationBilling(value: Mutable<OrganizationBilling>): void {
+  if (value.plan != null) {
+    reviveBillingPlan(value.plan);
+  }
+}
+
+export const getOrganizationBillingDescriptor = /* @__PURE__ */ callable({
+  address: '/organizations/{organizationId}/billing',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveOrganizationBilling) },
+} as const);
+
+function reviveOrganization(value: Mutable<Organization>): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('Organization.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+}
+
+function reviveOrganizationList(value: Mutable<OrganizationList>): void {
+  if (value.data != null) {
+    value.data.forEach((item) => {
+      reviveOrganization(item);
+    });
+  }
+}
+
+export const listOrganizationsDescriptor = /* @__PURE__ */ callable({
+  address: '/organizations',
+  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(reviveOrganizationList) },
+} as const);
+
+export const getOrganizationFields = { path: ['organizationId'] };
+
+export const getOrganizationDescriptor = /* @__PURE__ */ callable({
+  address: '/organizations/{organizationId}',
+  auth: apiKeyRequirements,
+  method: 'get',
+  returns: 'json',
+  validators: { response: /* @__PURE__ */ reviving(reviveOrganization) },
+} as const);
+
+/** Organizations, their plan limits, and their usage */
+export class Billing extends ElmoResource {
+  /**
+   * Get billing state
+   *
+   * The organization's plan, its limits, and how much of each limit is already spent — enough for
+   * an integration to know a write will be rejected before attempting it.
+   *
+   * This endpoint is read-only by construction. No API key of any kind can change a subscription,
+   * an add-on quantity, or a payment method; there is no billing write endpoint and no billing
+   * write scope. Stripe identifiers, invoices, and payment methods are never returned.
+   *
+   * Deployments without billing answer `200` with `billingEnabled: false`, a null plan, and null
+   * limits, so callers need no special case.
+   */
+  public get(
+    organizationId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<GetOrganizationBillingResponses, GetOrganizationBillingErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getOrganizationBillingDescriptor,
+      mergeParams(placeParams({ organizationId }, getOrganizationBillingFields, 'query'), options),
+    );
+  }
+}
+
+/** Organizations, their plan limits, and their usage */
+export class Organizations extends ElmoResource {
+  /**
+   * Get an organization
+   *
+   * No scope required. An organization outside the key's reach answers `404`, identically to one
+   * that does not exist.
+   */
+  public get(
+    organizationId: string,
+    options?: RequestOptions,
+  ): RestCallPromise<GetOrganizationResponses, GetOrganizationErrors> {
+    return callPromise(
+      options?.client ?? this.client,
+      getOrganizationDescriptor,
+      mergeParams(placeParams({ organizationId }, getOrganizationFields, 'query'), options),
+    );
+  }
+
+  /**
+   * One entry for an organization key — the one it acts inside. Every organization for an instance
+   * admin key. No scope required: a key can only ever see the organization it is already bound to.
+   */
+  public list(
+    params?: ListOrganizationsParams,
+    options?: RequestOptions,
+  ): PagePromise<Organization, OrganizationList, ListOrganizationsErrors> {
+    return pages(
+      options?.client ?? this.client,
+      listOrganizationsDescriptor,
+      mergeParams(groupParams(params, 'query'), options),
+    );
+  }
+
+  private _billing?: Billing;
+  /** Organizations, their plan limits, and their usage */
+  get billing(): Billing {
+    return (this._billing ??= new Billing(this.client));
+  }
+}
+
+export declare namespace Billing {
+  export type {
+    BillingPlan,
+    GetOrganizationBillingErrors,
+    GetOrganizationBillingResponses,
+    OrganizationBilling,
+    PlanLimits,
+  };
+}
+
+export declare namespace Organizations {
+  export type {
+    Billing,
+    BillingPlan,
+    GetOrganizationBillingErrors,
+    GetOrganizationBillingResponses,
+    GetOrganizationErrors,
+    GetOrganizationResponses,
+    ListOrganizationsErrors,
+    ListOrganizationsParams,
+    ListOrganizationsResponses,
+    Organization,
+    OrganizationBilling,
+    OrganizationList,
+    PlanLimits,
+  };
+}

package/src/resources/prompts.ts

@@ -0,0 +1,293 @@
+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 { 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 {
+  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: Mutable<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,212 @@
+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 { PagePromise, pages } from '../internal/core/page';
+import { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import type { Mutable } from '../internal/feature/validate';
+import { decoded } from '../internal/feature/validate';
+import type {
+  CreateReportErrors,
+  CreateReportParams,
+  CreateReportResponse,
+  CreateReportResponses,
+  GetReportErrors,
+  GetReportParams,
+  GetReportResponse,
+  GetReportResponses,
+  ListReportsErrors,
+  ListReportsParams,
+  ListReportsResponse,
+  ListReportsResponses,
+  ReportPromptSnapshot,
+  ReportSummary,
+} from '../types/reports';
+
+function reviveReportSummary(value: Mutable<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,
+  };
+}