@elmohq/sdk 0.1.0 → 0.1.2

package/src/internal/feature/retry.ts

@@ -1,7 +1,7 @@
 import { backoffDelay, exceedsMaxRetryAfter, retryAfterDelay, sleep } from '../core/backoff';
 import { discardBody, isStreamed } from '../core/body';
 import { calledOffWith, classifyError, ElmoError, failureOf, TransportError } from '../core/errors';
-import type { Feature, PreparedRequest, Result, RetryRules } from '../core/types';
+import type { Feature, PreparedRequest, Result, RetryRules, Send } from '../core/types';
 
 /** Which failed calls are sent again, how many times, and how long each waits first. */
 export interface RetryOptions extends RetryRules {
@@ -9,7 +9,7 @@ export interface RetryOptions extends RetryRules {
    * How long to wait before the next attempt, in milliseconds, in place of the
    * API's retry headers and the backoff. `undefined` keeps the usual wait.
    * After a failure that got no reply, `result` holds only the `error`.
-   * **{@link maxRetryAfter} does not limit what this returns.**
+   * {@link maxRetryAfter} does not limit what this returns.
    */
   retryDelay?(result: Result, request: PreparedRequest, attempt: number): number | undefined;
   /**
@@ -17,8 +17,9 @@ export interface RetryOptions extends RetryRules {
    * `retryOnTimeout`. After a reply, the body is unread: read it from
    * `response.clone()`. After a failure that got no reply, `result` holds only
    * the `error`. A call the API may have acted on is never asked about: a
-   * method outside `methods` is sent again only after 408, 425 or 429, or when
-   * the request never reached the API.
+   * method outside `methods` is sent again only after 408, 425 or 429, after
+   * a failure that answers `x-should-retry: true`, or when the request never
+   * reached the API.
    */
   retryOn?(result: Result, request: PreparedRequest): boolean;
 }
@@ -93,9 +94,12 @@ function shouldRetry(
 ): boolean {
   const { response } = result;
   if (!response) return false;
-  if (!repeatable && !REFUSED_STATUSES.includes(response.status)) return false;
+  const asked = response.headers.get(RETRY_HEADER);
+  const invited = asked === 'true' && response.status >= 400;
+  if (!repeatable && !invited && !REFUSED_STATUSES.includes(response.status)) return false;
   if (config.retryOn) return config.retryOn(result, request);
-  if (response.headers.get(RETRY_HEADER) === 'false') return false;
+  if (asked === 'false') return false;
+  if (invited) return true;
   const { statuses } = config;
   return statuses ? statuses.includes(response.status) : worthAnotherAttempt(response.status);
 }
@@ -115,51 +119,50 @@ function shouldRetryError(
 }
 
 export function retryFeature(options: RetryOptions = {}): Feature {
-  return {
-    name: 'retry',
-    async onSend(request, next) {
-      const config = isStreamed(request.body) ? undefined : resolveRetry(options, request);
-      if (!config) return next(request);
-
-      const attempts = (config.maxRetries ?? DEFAULT_MAX_RETRIES) + 1;
-      const repeatable = isRepeatable(config, request);
-      const started = Date.now();
-
-      for (let attempt = 0; ; attempt++) {
-        const last = attempt >= attempts - 1;
-        let result: Result | undefined;
-        let threw = false;
-        let wait: number | undefined;
-
-        if (attempt) request.attempt = attempt;
-        try {
-          result = await next(request);
-          if (last || !shouldRetry(config, result, request, repeatable)) return result;
-
-          wait = config.retryDelay?.(result, request, attempt);
-          if (wait === undefined) {
-            wait = askedFor(config, result);
-            if (exceedsMaxRetryAfter(wait, config.maxRetryAfter)) return result;
-          }
-        } catch (error) {
-          if (last || !shouldRetryError(config, error, request, repeatable)) throw error;
-          threw = true;
-          result = { error };
-          wait = config.retryDelay?.(result, request, attempt);
-        }
-
-        wait ??= backoffDelay(attempt, config);
-        if (config.budget !== undefined && Date.now() - started + wait >= config.budget) {
-          if (threw) throw result.error;
-          return result;
+  async function repeated(request: PreparedRequest, next: Send): Promise<Result> {
+    const config = isStreamed(request.body) ? undefined : resolveRetry(options, request);
+    if (!config) return next(request);
+
+    const attempts = (config.maxRetries ?? DEFAULT_MAX_RETRIES) + 1;
+    const repeatable = isRepeatable(config, request);
+    const started = Date.now();
+
+    for (let attempt = 0; ; attempt++) {
+      const last = attempt >= attempts - 1;
+      let result: Result | undefined;
+      let threw = false;
+      let wait: number | undefined;
+
+      if (attempt) request.attempt = attempt;
+      try {
+        result = await next(request);
+        if (last || !shouldRetry(config, result, request, repeatable)) return result;
+
+        wait = config.retryDelay?.(result, request, attempt);
+        if (wait === undefined) {
+          wait = askedFor(config, result);
+          if (exceedsMaxRetryAfter(wait, config.maxRetryAfter)) return result;
         }
+      } catch (error) {
+        if (last || !shouldRetryError(config, error, request, repeatable)) throw error;
+        threw = true;
+        result = { error };
+        wait = config.retryDelay?.(result, request, attempt);
+      }
 
-        discardBody(result);
-        request.log?.retrying(wait, attempt + 1, attempts - 1, result);
-        await sleep(wait, request.signal).catch((reason: unknown) => {
-          throw calledOffWith(reason);
-        });
+      wait ??= backoffDelay(attempt, config);
+      if (config.budget !== undefined && Date.now() - started + wait >= config.budget) {
+        if (threw) throw result.error;
+        return result;
       }
-    },
-  };
+
+      discardBody(result);
+      request.log?.retrying(wait, attempt + 1, attempts - 1, result);
+      await sleep(wait, request.signal).catch((reason: unknown) => {
+        throw calledOffWith(reason);
+      });
+    }
+  }
+
+  return { name: 'retry', onOpen: repeated, onSend: repeated };
 }

package/src/internal/feature/timeout.ts

@@ -131,7 +131,7 @@ export function timeoutFeature(options: TimeoutOptions = {}): Feature {
         request.signal = caller;
       });
     const { response } = result;
-    if (response?.body && (stream || request.options.unread)) {
+    if (response?.body && stream) {
       return { ...result, response: watchedReply(response, wait, done) };
     }
     done();
@@ -141,6 +141,6 @@ export function timeoutFeature(options: TimeoutOptions = {}): Feature {
   return {
     name: 'timeout',
     onOpen: (request, next) => bounded(request, next, true),
-    onSend: (request, next) => bounded(request, next, false),
+    onSend: (request, next) => bounded(request, next, !!request.options.unread),
   };
 }

package/src/internal/feature/validate.ts

@@ -66,6 +66,14 @@ export function decoded<TIn, TOut>(at: string, value: TIn, read: (value: TIn) =>
   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);

package/src/resources/analytics.ts

@@ -4,6 +4,7 @@ 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,
@@ -40,7 +41,7 @@ import type { BrandIdPath } from '../types/shared/brand-id-path';
 
 export const getBrandAnalyticsFields = { path: ['brandId'] };
 
-function reviveDateRange(value: DateRange): void {
+function reviveDateRange(value: Mutable<DateRange>): void {
   if (value.start != null) {
     value.start = decoded('DateRange.start', value.start, (raw) => new Date(raw));
   }
@@ -49,7 +50,7 @@ function reviveDateRange(value: DateRange): void {
   }
 }
 
-function reviveBrandAnalytics(value: BrandAnalytics): void {
+function reviveBrandAnalytics(value: Mutable<BrandAnalytics>): void {
   if (value.range != null) {
     reviveDateRange(value.range);
   }
@@ -65,7 +66,7 @@ export const getBrandAnalyticsDescriptor = /* @__PURE__ */ callable({
 
 export const listBrandCitationDomainsFields = { path: ['brandId'] };
 
-function reviveCitationDomainList(value: CitationDomainList): void {
+function reviveCitationDomainList(value: Mutable<CitationDomainList>): void {
   if (value.range != null) {
     reviveDateRange(value.range);
   }
@@ -81,7 +82,7 @@ export const listBrandCitationDomainsDescriptor = /* @__PURE__ */ callable({
 
 export const listBrandCitationUrlsFields = { path: ['brandId'] };
 
-function reviveCitationUrlList(value: CitationURLList): void {
+function reviveCitationUrlList(value: Mutable<CitationURLList>): void {
   if (value.range != null) {
     reviveDateRange(value.range);
   }
@@ -97,7 +98,7 @@ export const listBrandCitationURLsDescriptor = /* @__PURE__ */ callable({
 
 export const listBrandPromptPerformanceFields = { path: ['brandId'] };
 
-function revivePromptPerformance(value: PromptPerformanceSchema): void {
+function revivePromptPerformance(value: Mutable<PromptPerformanceSchema>): void {
   if (value.lastRunAt != null) {
     value.lastRunAt = decoded(
       'PromptPerformance.lastRunAt',
@@ -114,7 +115,7 @@ function revivePromptPerformance(value: PromptPerformanceSchema): void {
   }
 }
 
-function revivePromptPerformanceList(value: PromptPerformanceList): void {
+function revivePromptPerformanceList(value: Mutable<PromptPerformanceList>): void {
   if (value.range != null) {
     reviveDateRange(value.range);
   }
@@ -135,7 +136,7 @@ export const listBrandPromptPerformanceDescriptor = /* @__PURE__ */ callable({
 
 export const getBrandQueryFanoutFields = { path: ['brandId'] };
 
-function reviveBrandQueryFanout(value: BrandQueryFanout): void {
+function reviveBrandQueryFanout(value: Mutable<BrandQueryFanout>): void {
   if (value.range != null) {
     reviveDateRange(value.range);
   }

package/src/resources/brands.ts

@@ -7,9 +7,10 @@ import { brandNameRule, domainsRule, nameRule } from './shared/rule';
 import { Tags } from './tags';
 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 { PagePromise, pages } from '../internal/page/page';
 import type {
   BrandAnalytics,
   BrandQueryFanout,
@@ -26,6 +27,7 @@ import type {
   ListBrandPromptPerformanceResponses,
   ModelVisibility,
   PromptPerformanceList,
+  PromptPerformance as PromptPerformanceSchema,
   ShareOfVoiceEntry,
   ShareOfVoicePoint,
   TagsFilter,
@@ -57,7 +59,7 @@ import type {
 import type { BrandIdPath } from '../types/shared/brand-id-path';
 import type { ListBrandTagsErrors, ListBrandTagsResponses, Tag, TagList } from '../types/tags';
 
-function reviveBrand(value: Brand): void {
+function reviveBrand(value: Mutable<Brand>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('Brand.createdAt', value.createdAt, (raw) => new Date(raw));
   }
@@ -66,7 +68,7 @@ function reviveBrand(value: Brand): void {
   }
 }
 
-function reviveBrandsList(value: BrandsList): void {
+function reviveBrandsList(value: Mutable<BrandsList>): void {
   if (value.data != null) {
     value.data.forEach((item) => {
       reviveBrand(item);
@@ -268,8 +270,9 @@ export declare namespace Brands {
     Opportunities,
     Opportunity,
     OpportunityPrompt,
-    PromptPerformance,
+    PromptPerformanceSchema as PromptPerformance,
     PromptPerformanceList,
+    PromptPerformance as PromptPerformanceResource,
     QueryFanout,
     ShareOfVoiceEntry,
     ShareOfVoicePoint,

package/src/resources/competitors.ts

@@ -4,9 +4,10 @@ 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 { 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 { PagePromise, pages } from '../internal/page/page';
 import type {
   Competitor,
   CompetitorsList,
@@ -25,7 +26,7 @@ import type {
   UpdateCompetitorResponses,
 } from '../types/competitors';
 
-function reviveCompetitor(value: Competitor): void {
+function reviveCompetitor(value: Mutable<Competitor>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('Competitor.createdAt', value.createdAt, (raw) => new Date(raw));
   }
@@ -34,7 +35,7 @@ function reviveCompetitor(value: Competitor): void {
   }
 }
 
-function reviveCompetitorsList(value: CompetitorsList): void {
+function reviveCompetitorsList(value: Mutable<CompetitorsList>): void {
   if (value.data != null) {
     value.data.forEach((item) => {
       reviveCompetitor(item);

package/src/resources/identity.ts

@@ -3,10 +3,11 @@ 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 { Mutable } from '../internal/feature/validate';
 import { decoded, reviving } from '../internal/feature/validate';
 import type { APIKeyIdentity, GetMeErrors, GetMeResponses } from '../types/identity';
 
-function reviveApiKeyIdentity(value: APIKeyIdentity): void {
+function reviveApiKeyIdentity(value: Mutable<APIKeyIdentity>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('ApiKeyIdentity.createdAt', value.createdAt, (raw) => new Date(raw));
   }

package/src/resources/opportunities.ts

@@ -4,6 +4,7 @@ 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 {
   BrandOpportunities,
@@ -17,7 +18,7 @@ import type { BrandIdPath } from '../types/shared/brand-id-path';
 
 export const getBrandOpportunitiesFields = { path: ['brandId'] };
 
-function reviveBrandOpportunities(value: BrandOpportunities): void {
+function reviveBrandOpportunities(value: Mutable<BrandOpportunities>): void {
   if (value.generatedAt != null) {
     value.generatedAt = decoded(
       'BrandOpportunities.generatedAt',
@@ -32,6 +33,7 @@ export const getBrandOpportunitiesDescriptor = /* @__PURE__ */ callable({
   auth: apiKeyRequirements,
   method: 'get',
   returns: 'json',
+  timeout: 600000,
   validators: { response: /* @__PURE__ */ reviving(reviveBrandOpportunities) },
 } as const);
 

package/src/resources/organizations.ts

@@ -3,9 +3,10 @@ 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 { PagePromise, pages } from '../internal/page/page';
 import type {
   BillingPlan,
   GetOrganizationBillingErrors,
@@ -23,13 +24,13 @@ import type {
 
 export const getOrganizationBillingFields = { path: ['organizationId'] };
 
-function reviveBillingPlan(value: BillingPlan): void {
+function reviveBillingPlan(value: Mutable<BillingPlan>): void {
   if (value.periodEnd != null) {
     value.periodEnd = decoded('BillingPlan.periodEnd', value.periodEnd, (raw) => new Date(raw));
   }
 }
 
-function reviveOrganizationBilling(value: OrganizationBilling): void {
+function reviveOrganizationBilling(value: Mutable<OrganizationBilling>): void {
   if (value.plan != null) {
     reviveBillingPlan(value.plan);
   }
@@ -43,13 +44,13 @@ export const getOrganizationBillingDescriptor = /* @__PURE__ */ callable({
   validators: { response: /* @__PURE__ */ reviving(reviveOrganizationBilling) },
 } as const);
 
-function reviveOrganization(value: Organization): void {
+function reviveOrganization(value: Mutable<Organization>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('Organization.createdAt', value.createdAt, (raw) => new Date(raw));
   }
 }
 
-function reviveOrganizationList(value: OrganizationList): void {
+function reviveOrganizationList(value: Mutable<OrganizationList>): void {
   if (value.data != null) {
     value.data.forEach((item) => {
       reviveOrganization(item);

package/src/resources/prompts.ts

@@ -6,9 +6,10 @@ 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 { PagePromise, pages } from '../internal/page/page';
 import type {
   CreatePromptErrors,
   CreatePromptParams,
@@ -46,7 +47,7 @@ import type {
   PromptSnapshot,
 } from '../types/snapshots';
 
-function revivePrompt(value: Prompt): void {
+function revivePrompt(value: Mutable<Prompt>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('Prompt.createdAt', value.createdAt, (raw) => new Date(raw));
   }

package/src/resources/reports.ts

@@ -4,9 +4,10 @@ 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 { PagePromise, pages } from '../internal/page/page';
 import type {
   CreateReportErrors,
   CreateReportParams,
@@ -24,7 +25,7 @@ import type {
   ReportSummary,
 } from '../types/reports';
 
-function reviveReportSummary(value: ReportSummary): void {
+function reviveReportSummary(value: Mutable<ReportSummary>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('ReportSummary.createdAt', value.createdAt, (raw) => new Date(raw));
   }

package/src/resources/runs.ts

@@ -3,9 +3,10 @@ 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 { PagePromise, pages } from '../internal/page/page';
 import type {
   GetRunErrors,
   GetRunResponses,
@@ -20,13 +21,13 @@ import type {
 
 export const listPromptRunsFields = { path: ['promptId'] };
 
-function reviveRunSummary(value: RunSummary): void {
+function reviveRunSummary(value: Mutable<RunSummary>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('RunSummary.createdAt', value.createdAt, (raw) => new Date(raw));
   }
 }
 
-function reviveRunList(value: RunList): void {
+function reviveRunList(value: Mutable<RunList>): void {
   if (value.data != null) {
     value.data.forEach((item) => {
       reviveRunSummary(item);
@@ -53,7 +54,7 @@ export const listPromptRunsDescriptor = /* @__PURE__ */ callable({
 
 export const getRunFields = { path: ['promptId', 'runId'] };
 
-function reviveRun(value: Run): void {
+function reviveRun(value: Mutable<Run>): void {
   if (value.createdAt != null) {
     value.createdAt = decoded('Run.createdAt', value.createdAt, (raw) => new Date(raw));
   }

package/src/resources/tools.ts

@@ -34,6 +34,7 @@ export const analyzeBrandDescriptor = /* @__PURE__ */ callable({
       name: 'maxPrompts',
     },
   ],
+  timeout: 600000,
 } as const);
 
 /** One-shot helpers (e.g. brand analysis) that don't persist anything */

package/src/types/analytics.ts

@@ -408,14 +408,16 @@ export type GetBrandQueryFanoutResponses = {
 
 export type GetBrandAnalyticsParams = {
   /**
-   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
-   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
-   * local calendar day there.
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`.
+   * Aligned down to the quarter hour, the grain analytics are aggregated at; where a response
+   * repeats the window, it repeats the aligned one. A bare `YYYY-MM-DD` is rejected: that is
+   * `/prompts/{promptId}/snapshot`'s spelling and means a local calendar day there.
    */
   start: WindowStart;
   /**
-   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
-   * exactly `end` is outside it.
+   * Exclusive upper bound of the window, an ISO 8601 timestamp, also aligned down to the quarter
+   * hour. The window is half-open: a run at exactly `end` is outside it. `start` and `end` inside
+   * one quarter-hour bucket leave an empty window and are rejected.
    */
   end: WindowEnd;
   /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */
@@ -426,14 +428,16 @@ export type GetBrandAnalyticsParams = {
 
 export type ListBrandCitationDomainsParams = {
   /**
-   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
-   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
-   * local calendar day there.
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`.
+   * Aligned down to the quarter hour, the grain analytics are aggregated at; where a response
+   * repeats the window, it repeats the aligned one. A bare `YYYY-MM-DD` is rejected: that is
+   * `/prompts/{promptId}/snapshot`'s spelling and means a local calendar day there.
    */
   start: WindowStart;
   /**
-   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
-   * exactly `end` is outside it.
+   * Exclusive upper bound of the window, an ISO 8601 timestamp, also aligned down to the quarter
+   * hour. The window is half-open: a run at exactly `end` is outside it. `start` and `end` inside
+   * one quarter-hour bucket leave an empty window and are rejected.
    */
   end: WindowEnd;
   /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */
@@ -444,14 +448,16 @@ export type ListBrandCitationDomainsParams = {
 
 export type ListBrandCitationURLsParams = {
   /**
-   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
-   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
-   * local calendar day there.
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`.
+   * Aligned down to the quarter hour, the grain analytics are aggregated at; where a response
+   * repeats the window, it repeats the aligned one. A bare `YYYY-MM-DD` is rejected: that is
+   * `/prompts/{promptId}/snapshot`'s spelling and means a local calendar day there.
    */
   start: WindowStart;
   /**
-   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
-   * exactly `end` is outside it.
+   * Exclusive upper bound of the window, an ISO 8601 timestamp, also aligned down to the quarter
+   * hour. The window is half-open: a run at exactly `end` is outside it. `start` and `end` inside
+   * one quarter-hour bucket leave an empty window and are rejected.
    */
   end: WindowEnd;
   /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */
@@ -462,14 +468,16 @@ export type ListBrandCitationURLsParams = {
 
 export type ListBrandPromptPerformanceParams = {
   /**
-   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
-   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
-   * local calendar day there.
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`.
+   * Aligned down to the quarter hour, the grain analytics are aggregated at; where a response
+   * repeats the window, it repeats the aligned one. A bare `YYYY-MM-DD` is rejected: that is
+   * `/prompts/{promptId}/snapshot`'s spelling and means a local calendar day there.
    */
   start: WindowStart;
   /**
-   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
-   * exactly `end` is outside it.
+   * Exclusive upper bound of the window, an ISO 8601 timestamp, also aligned down to the quarter
+   * hour. The window is half-open: a run at exactly `end` is outside it. `start` and `end` inside
+   * one quarter-hour bucket leave an empty window and are rejected.
    */
   end: WindowEnd;
   /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */
@@ -480,14 +488,16 @@ export type ListBrandPromptPerformanceParams = {
 
 export type GetBrandQueryFanoutParams = {
   /**
-   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
-   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
-   * local calendar day there.
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`.
+   * Aligned down to the quarter hour, the grain analytics are aggregated at; where a response
+   * repeats the window, it repeats the aligned one. A bare `YYYY-MM-DD` is rejected: that is
+   * `/prompts/{promptId}/snapshot`'s spelling and means a local calendar day there.
    */
   start: WindowStart;
   /**
-   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
-   * exactly `end` is outside it.
+   * Exclusive upper bound of the window, an ISO 8601 timestamp, also aligned down to the quarter
+   * hour. The window is half-open: a run at exactly `end` is outside it. `start` and `end` inside
+   * one quarter-hour bucket leave an empty window and are rejected.
    */
   end: WindowEnd;
   /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */

package/src/types/runs.ts

@@ -101,14 +101,16 @@ export type GetRunResponses = {
 
 export type ListPromptRunsParams = {
   /**
-   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`. A
-   * bare `YYYY-MM-DD` is rejected: that is `/prompts/{promptId}/snapshot`'s spelling and means a
-   * local calendar day there.
+   * Inclusive lower bound of the window, an ISO 8601 timestamp such as `2026-01-01T00:00:00Z`.
+   * Aligned down to the quarter hour, the grain analytics are aggregated at; where a response
+   * repeats the window, it repeats the aligned one. A bare `YYYY-MM-DD` is rejected: that is
+   * `/prompts/{promptId}/snapshot`'s spelling and means a local calendar day there.
    */
   start: WindowStart;
   /**
-   * Exclusive upper bound of the window, an ISO 8601 timestamp. The window is half-open: a run at
-   * exactly `end` is outside it.
+   * Exclusive upper bound of the window, an ISO 8601 timestamp, also aligned down to the quarter
+   * hour. The window is half-open: a run at exactly `end` is outside it. `start` and `end` inside
+   * one quarter-hour bucket leave an empty window and are rejected.
    */
   end: WindowEnd;
   /** Restrict to one model, e.g. `chatgpt`. See `models.list()`. */