@elmohq/sdk 0.0.0-claim → 0.1.0

package/src/resources/competitors.ts

@@ -0,0 +1,212 @@
+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 { groupParams, mergeParams, placeParams } from '../internal/core/params';
+import { decoded, reviving } from '../internal/feature/validate';
+import { PagePromise, pages } from '../internal/page/page';
+import type {
+  Competitor,
+  CompetitorsList,
+  CreateCompetitorErrors,
+  CreateCompetitorParams,
+  CreateCompetitorResponses,
+  DeleteCompetitorErrors,
+  DeleteCompetitorResponses,
+  GetCompetitorErrors,
+  GetCompetitorResponses,
+  ListCompetitorsErrors,
+  ListCompetitorsParams,
+  ListCompetitorsResponses,
+  UpdateCompetitorErrors,
+  UpdateCompetitorParams,
+  UpdateCompetitorResponses,
+} from '../types/competitors';
+
+function reviveCompetitor(value: 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: 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,48 @@
+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 { decoded, reviving } from '../internal/feature/validate';
+import type { APIKeyIdentity, GetMeErrors, GetMeResponses } from '../types/identity';
+
+function reviveApiKeyIdentity(value: 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,79 @@
+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 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: 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',
+  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,
+  };
+}

package/src/resources/organizations.ts

@@ -0,0 +1,181 @@
+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, placeParams } from '../internal/core/params';
+import { decoded, reviving } from '../internal/feature/validate';
+import { PagePromise, pages } from '../internal/page/page';
+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: BillingPlan): void {
+  if (value.periodEnd != null) {
+    value.periodEnd = decoded('BillingPlan.periodEnd', value.periodEnd, (raw) => new Date(raw));
+  }
+}
+
+function reviveOrganizationBilling(value: 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: Organization): void {
+  if (value.createdAt != null) {
+    value.createdAt = decoded('Organization.createdAt', value.createdAt, (raw) => new Date(raw));
+  }
+}
+
+function reviveOrganizationList(value: 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,
+  };
+}