@tidblink/server 0.0.0-stage → 0.3.0-rc.0

package/dist/turn.js

@@ -0,0 +1,206 @@
+import { OutcomeUnknownError, TiDBLinkApiError, TiDBLinkError, TurnFailedError, TurnInterruptedError, TurnWaitTimeoutError, InputNotAppliedError, } from "./errors.js";
+import { HttpClient, sleep, requireCreationKey, requireKnownKeys, } from "./http.js";
+import { getInteraction, getTurn, requireInteraction, } from "./history.js";
+export const validClarification = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const item = value;
+    const strings = (items, min, max) => Array.isArray(items) &&
+        items.length >= min &&
+        items.length <= max &&
+        items.every((text) => typeof text === "string" && text.length > 0);
+    if (typeof item.prompt !== "string" ||
+        !item.prompt ||
+        (item.selectionMode !== "single" && item.selectionMode !== "multiple") ||
+        !strings(item.answerChoices, 2, item.selectionMode === "single" ? 3 : 8))
+        return false;
+    if (item.response === undefined)
+        return true;
+    if (typeof item.response !== "object" ||
+        item.response === null ||
+        Array.isArray(item.response))
+        return false;
+    const response = item.response;
+    return (Object.keys(response).sort().join(",") === "answers,responseTurnId" &&
+        typeof response.responseTurnId === "string" &&
+        response.responseTurnId.length > 0 &&
+        strings(response.answers, 1, item.selectionMode === "single" ? 1 : 9));
+};
+export const submitMessage = async (http, sessionId, input) => {
+    requireKnownKeys(input, [
+        "clientEventId",
+        "text",
+        "userFileIds",
+        "clarificationSourceTurnId",
+        "billingTag",
+        "requestId",
+        "signal",
+    ], "Message input");
+    requireCreationKey(input.clientEventId);
+    const { clientEventId, requestId, signal, ...data } = input;
+    const texts = typeof data.text === "string" ? [data.text] : data.text;
+    if (!Array.isArray(texts) ||
+        texts.length < 1 ||
+        texts.length > 9 ||
+        texts.some((t) => typeof t !== "string" || !t))
+        throw new TypeError("text must contain 1-9 non-empty values");
+    if (data.userFileIds !== undefined &&
+        (!Array.isArray(data.userFileIds) ||
+            data.userFileIds.length > 20 ||
+            data.userFileIds.some((id) => typeof id !== "string" || !id || id.length > 64)))
+        throw new TypeError("userFileIds must contain at most 20 non-empty IDs");
+    if (data.clarificationSourceTurnId !== undefined &&
+        (typeof data.clarificationSourceTurnId !== "string" ||
+            !data.clarificationSourceTurnId ||
+            data.clarificationSourceTurnId.length > 64))
+        throw new TypeError("clarificationSourceTurnId must contain 1-64 characters");
+    signal?.throwIfAborted();
+    try {
+        const result = await http.postResponse(`/api/v1/user/sessions/${encodeURIComponent(sessionId)}/events`, { type: "agent.session.input.message", clientEventId, data }, {
+            ...(requestId ? { requestId } : {}),
+            ...(signal ? { signal } : {}),
+            outcomeUnknown: true,
+        });
+        try {
+            const receipt = requireInteraction(result.data?.interaction, clientEventId, result.requestId);
+            if (receipt.kind !== "message" ||
+                !receipt.message ||
+                receipt.message.role !== "user")
+                throw new TiDBLinkError("Message submission returned a different command receipt");
+            return receipt;
+        }
+        catch (cause) {
+            throw new OutcomeUnknownError("Message submission returned no usable receipt; query the original input", { requestId: result.requestId, cause });
+        }
+    }
+    catch (cause) {
+        if (!(cause instanceof OutcomeUnknownError))
+            throw cause;
+        throw new OutcomeUnknownError(cause.message, {
+            sessionId,
+            inputId: clientEventId,
+            ...(cause.requestId ? { requestId: cause.requestId } : {}),
+            cause,
+        });
+    }
+};
+export const validateWaitOptions = (options = {}) => {
+    requireKnownKeys(options, ["timeoutMs", "pollIntervalMs", "requestId", "signal"], "Wait options");
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < 0 ||
+        timeoutMs > 2_147_483_647)
+        throw new TypeError("timeoutMs must be an integer between 0 and 2147483647");
+    if (!Number.isSafeInteger(pollIntervalMs) ||
+        pollIntervalMs < 1 ||
+        pollIntervalMs > 2_147_483_647)
+        throw new TypeError("pollIntervalMs must be an integer between 1 and 2147483647");
+    return { timeoutMs, pollIntervalMs };
+};
+export const waitForResult = async (http, sessionId, inputId, options = {}) => {
+    const { timeoutMs, pollIntervalMs } = validateWaitOptions(options);
+    requireCreationKey(inputId);
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, deadline.signal])
+        : deadline.signal;
+    let turnId;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const interaction = await getInteraction(http, sessionId, inputId, {
+                signal,
+                ...(options.requestId ? { requestId: options.requestId } : {}),
+            });
+            turnId = interaction.turnId;
+            if ((interaction.kind !== "message" && interaction.kind !== "retry") ||
+                (interaction.kind === "message" &&
+                    (!interaction.message || interaction.message.role !== "user")) ||
+                (interaction.kind === "retry" && interaction.message !== null))
+                throw new TiDBLinkError("Waiting for a result requires a message or checkpoint retry receipt");
+            if (interaction.rejection || interaction.mode === "rejected")
+                throw new InputNotAppliedError(sessionId, inputId, turnId);
+            if (interaction.result.status !== "running" &&
+                !interaction.result.completedAt)
+                throw new TiDBLinkError("Original terminal receipt omitted its completion time");
+            if (interaction.result.status === "failed")
+                throw new TurnFailedError({
+                    code: "turn_failed",
+                    message: "The original Turn execution failed",
+                    turnId,
+                    sessionId,
+                    inputId,
+                });
+            if (interaction.result.status === "interrupted")
+                throw new TurnInterruptedError(turnId, undefined, sessionId, inputId);
+            if (interaction.result.status === "succeeded") {
+                if (interaction.kind === "message" && !interaction.appliedAt)
+                    throw new InputNotAppliedError(sessionId, inputId, turnId);
+                const turn = await getTurn(http, sessionId, turnId, {
+                    signal,
+                    ...(options.requestId ? { requestId: options.requestId } : {}),
+                });
+                const message = turn.assistantMessage;
+                if (turn.executor === "realtime_model" ||
+                    turn.status !== "succeeded" ||
+                    !interaction.result.completedAt ||
+                    turn.completedAt !== interaction.result.completedAt ||
+                    !message ||
+                    message.role !== "assistant" ||
+                    typeof message.id !== "string" ||
+                    !message.id ||
+                    typeof message.content !== "string" ||
+                    message.turnId !== turnId ||
+                    message.sessionId !== sessionId ||
+                    (turn.clarificationItem !== undefined &&
+                        !validClarification(turn.clarificationItem)))
+                    throw new TiDBLinkError("Saved Turn does not match the original successful execution");
+                const identity = {
+                    sessionId,
+                    inputId,
+                    turnId,
+                    messageId: message.id,
+                    text: message.content,
+                    interaction,
+                };
+                return turn.clarificationItem
+                    ? {
+                        ...identity,
+                        type: "clarification",
+                        clarification: turn.clarificationItem,
+                    }
+                    : { ...identity, type: "answer" };
+            }
+            await sleep(pollIntervalMs, signal);
+        }
+    }
+    catch (cause) {
+        if (cause instanceof TurnFailedError ||
+            cause instanceof TurnInterruptedError ||
+            cause instanceof InputNotAppliedError ||
+            cause instanceof TiDBLinkApiError)
+            throw cause;
+        const ErrorClass = deadline.signal.aborted && !options.signal?.aborted
+            ? TurnWaitTimeoutError
+            : OutcomeUnknownError;
+        throw new ErrorClass(ErrorClass === TurnWaitTimeoutError
+            ? "Local wait timed out; query or wait for the original input"
+            : "Local wait stopped before the original result was established", {
+            sessionId,
+            inputId,
+            ...(turnId ? { turnId } : {}),
+            ...(cause instanceof TiDBLinkError && cause.requestId
+                ? { requestId: cause.requestId }
+                : options.requestId
+                    ? { requestId: options.requestId }
+                    : {}),
+            cause,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+//# sourceMappingURL=turn.js.map

package/dist/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../src/turn.ts"],"names":[],"mappings":"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"}

package/dist/usage.d.ts

@@ -0,0 +1,462 @@
+import type { RequestOptions } from "./organization.js";
+import type { BillingTag } from "./session.js";
+export type BillingUsageFactKind = "llm" | "sandbox" | "web_search";
+export type BillingCostBearer = "platform" | "customer" | "unknown";
+export type BillingPrincipalBucket = "human" | "user_api_key" | "organization_machine" | "organization_user";
+export type BillingAttributionKind = "agent" | "user_level" | "system" | "unattributed";
+export type BillingAuthKind = "session" | "user-api-key" | "organization-api-key" | "system";
+export type BillingLlmRequestPurpose = "agent_turn" | "compaction" | "auto_title" | "manual_title" | "asr" | "voice_realtime";
+export type LlmPricingStatus = "estimated" | "unknown";
+export type LlmPricingContextTier = "short" | "long" | "all_context" | "unknown";
+export type SandboxUsageStatus = "running" | "closed" | "close_failed" | "abandoned";
+export type BillingUsageEvidenceStatus = "complete" | "partial" | "missing" | "unsupported";
+export type BillingValuationStatus = "priced" | "unpriced";
+export interface BillingValuationSummary {
+    status: "complete" | "incomplete";
+    pricedUsageCount: number;
+    unpricedUsageCount: number;
+    pricedCostMicros: number;
+}
+export interface BillingValuationBreakdown extends BillingValuationSummary {
+    byKind: Partial<Record<BillingUsageFactKind, BillingValuationSummary>>;
+}
+export interface BillingFactCompletenessCounters {
+    status: "complete" | "incomplete";
+    projectedFactCount: number;
+    pendingIntentCount: number;
+    indeterminateIntentCount: number;
+    failedIntentCount: number;
+}
+export interface BillingFactCompleteness extends BillingFactCompletenessCounters {
+    byKind: Partial<Record<BillingUsageFactKind, BillingFactCompletenessCounters>>;
+}
+export type UserUsageScopeLevel = "user";
+export type UserUsagePeriod = "day" | "week";
+export interface UserUsageScope {
+    level: UserUsageScopeLevel;
+    organizationId: string;
+    userId: string;
+}
+export interface UserUsageRange {
+    period: UserUsagePeriod;
+    from: string;
+    to: string;
+}
+export interface UsageTotals {
+    currency: "USD";
+    /** Platform-borne priced cost; other bearers remain in costByBearer. */
+    totalCostMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+    costByBearer: Record<BillingCostBearer, BillingBearerCostTotals>;
+    organizationMachineCostMicros: number;
+    llmRequestCount: number;
+    unknownLlmRequestCount: number;
+    sandboxUsageCount: number;
+    webSearchRequestCount: number;
+    unsettledCount: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    unpricedLlmTokens: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+    };
+    sandboxDurationSeconds: number;
+    valuation: BillingValuationBreakdown;
+    attribution: BillingAttributionBreakdown;
+}
+export interface BillingBearerCostTotals {
+    totalCostMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+}
+export interface BillingAttributionCounters {
+    status: "complete" | "incomplete";
+    classifiedUsageCount: number;
+    agentUsageCount: number;
+    userLevelUsageCount: number;
+    systemUsageCount: number;
+    unattributedUsageCount: number;
+}
+export interface BillingAttributionBreakdown extends BillingAttributionCounters {
+    byKind: Partial<Record<BillingUsageFactKind, BillingAttributionCounters>>;
+}
+export interface LlmUsageAggregate {
+    costBearer: BillingCostBearer;
+    provider: string;
+    model: string;
+    requestPurpose: BillingLlmRequestPurpose;
+    principalBucket: BillingPrincipalBucket;
+    requestCount: number;
+    unknownRequestCount: number;
+    costMicros: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    valuation: BillingValuationSummary;
+}
+export interface UserUsageAggregate {
+    costBearer: BillingCostBearer;
+    userId: string;
+    displayName: string | null;
+    currency: "USD";
+    totalCostMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+    llmRequestCount: number;
+    unknownLlmRequestCount: number;
+    sandboxUsageCount: number;
+    webSearchRequestCount: number;
+    unsettledCount: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    sandboxDurationSeconds: number;
+    valuation: BillingValuationSummary;
+}
+export interface SandboxUsageAggregate {
+    costBearer: BillingCostBearer;
+    provider: "e2b" | "tencent_ags" | "run9";
+    profileId: string;
+    specKey: string;
+    principalBucket: BillingPrincipalBucket;
+    usageCount: number;
+    settledUsageCount: number;
+    unsettledCount: number;
+    costMicros: number;
+    durationSeconds: number;
+    valuation: BillingValuationSummary;
+}
+export interface WebSearchUsageAggregate {
+    costBearer: BillingCostBearer;
+    provider: "exa";
+    searchType: "auto";
+    principalBucket: BillingPrincipalBucket;
+    requestCount: number;
+    requestedResultCount: number;
+    returnedResultCount: number;
+    costMicros: number;
+    valuation: BillingValuationSummary;
+}
+export interface UsageDayPoint {
+    date: string;
+    costMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+    unknownLlmRequestCount: number;
+    unsettledCount: number;
+    valuation: BillingValuationSummary;
+}
+export type BillingUsageSeriesInterval = "hour" | "day" | "week" | "month";
+export interface BillingUsageSeriesRange {
+    from: string;
+    to: string;
+    interval: BillingUsageSeriesInterval;
+}
+interface BillingUsageSeriesBreakdownCommon {
+    provider: string;
+    costMicros: number;
+    truncatedCombinations?: number;
+}
+export interface BillingUsageSeriesLlmBreakdown extends BillingUsageSeriesBreakdownCommon {
+    kind: "llm";
+    model?: string;
+    usage: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface BillingUsageSeriesSandboxBreakdown extends BillingUsageSeriesBreakdownCommon {
+    kind: "sandbox";
+    usage: {
+        durationSeconds: number;
+        usageCount: number;
+    };
+}
+export interface BillingUsageSeriesWebSearchBreakdown extends BillingUsageSeriesBreakdownCommon {
+    kind: "web_search";
+    usage: {
+        requestCount: number;
+    };
+}
+export type BillingUsageSeriesBreakdown = BillingUsageSeriesLlmBreakdown | BillingUsageSeriesSandboxBreakdown | BillingUsageSeriesWebSearchBreakdown;
+export type BillingUsageSeriesBreakdownGroups = Record<BillingCostBearer, BillingUsageSeriesBreakdown[]>;
+export interface BillingUsageSeriesPoint {
+    bucketStart: string;
+    costMicros: number;
+    llmCostMicros: number;
+    sandboxCostMicros: number;
+    webSearchCostMicros: number;
+    unknownLlmRequestCount: number;
+    unsettledCount: number;
+    breakdown: BillingUsageSeriesBreakdownGroups;
+    valuation: BillingValuationSummary;
+}
+export interface UserUsageSummary {
+    scope: UserUsageScope;
+    range: UserUsageRange;
+    factCompleteness: BillingFactCompleteness;
+    totals: UsageTotals;
+    users: {
+        aggregates: UserUsageAggregate[];
+    };
+    llm: {
+        aggregates: LlmUsageAggregate[];
+    };
+    sandbox: {
+        aggregates: SandboxUsageAggregate[];
+    };
+    webSearch: {
+        aggregates: WebSearchUsageAggregate[];
+    };
+    series: UsageDayPoint[];
+}
+export interface UserLlmUsage {
+    kind: "llm";
+    id: string;
+    occurredAt: string;
+    organizationId: string;
+    sessionId: string;
+    /** Null only for Realtime connection-scoped usage (`requestPurpose: voice_realtime`). */
+    turnId: string | null;
+    /** The Realtime connection of `voice_realtime` usage; null otherwise. */
+    realtimeConnectionId: string | null;
+    agentRunId: string | null;
+    agentId: string | null;
+    attributionKind: BillingAttributionKind;
+    ownerUserId: string | null;
+    authKind: BillingAuthKind;
+    principalBucket: BillingPrincipalBucket;
+    billingTag: BillingTag | null;
+    operationId: string | null;
+    requestPurpose: BillingLlmRequestPurpose;
+    provider: string;
+    requestModel: string;
+    observedResponseModel: string | null;
+    model: string;
+    providerRequestId: string | null;
+    inputTokens: number;
+    cachedInputTokens: number;
+    promptTokensTotal: number | null;
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    cacheWriteUnspecifiedTokens: number;
+    outputTokens: number;
+    inputCostMicros: number | null;
+    cachedInputCostMicros: number | null;
+    cacheWrite5mCostMicros: number | null;
+    cacheWrite1hCostMicros: number | null;
+    cacheWriteUnspecifiedCostMicros: number | null;
+    outputCostMicros: number | null;
+    costMicros: number | null;
+    currency: "USD";
+    ratedAt: string;
+    pricingStatus: LlmPricingStatus;
+    unknownReason: string | null;
+    estimateBasis: "public_list_placeholder" | "contract" | null;
+    estimateLabel: string | null;
+    contextTier: LlmPricingContextTier;
+    pricingVersion: string;
+    rateCardDigest: string | null;
+    pricingSourceUrl: string | null;
+    pricingSourceAsOf: string | null;
+    pricingEffectiveAt: string;
+    pricingEffectiveToExclusive: string | null;
+    deploymentBillingJson: unknown | null;
+    rateSnapshotJson: unknown | null;
+    valuationStatus: BillingValuationStatus;
+}
+export interface UserSandboxUsage {
+    kind: "sandbox";
+    id: string;
+    occurredAt: string;
+    organizationId: string;
+    sessionId: string;
+    turnId: string;
+    agentRunId: string | null;
+    agentId: string | null;
+    attributionKind: BillingAttributionKind;
+    ownerUserId: string | null;
+    authKind: BillingAuthKind;
+    principalBucket: BillingPrincipalBucket;
+    billingTag: BillingTag | null;
+    provider: "e2b" | "tencent_ags" | "run9";
+    profileId: string;
+    specKey: string;
+    startedAt: string;
+    lastSeenAt: string;
+    endedAt: string | null;
+    durationSeconds: number | null;
+    status: SandboxUsageStatus;
+    closeReason: string | null;
+    lastError: string | null;
+    costMicros: number | null;
+    currency: "USD";
+    pricingVersion: string;
+    pricingEffectiveAt: string;
+    valuationStatus: BillingValuationStatus;
+}
+export interface UserWebSearchUsage {
+    kind: "web_search";
+    id: string;
+    occurredAt: string;
+    organizationId: string;
+    sessionId: string;
+    turnId: string;
+    agentRunId: string | null;
+    agentId: string | null;
+    ownerUserId: string | null;
+    attributionKind: BillingAttributionKind;
+    authKind: BillingAuthKind;
+    principalBucket: BillingPrincipalBucket;
+    billingTag: BillingTag | null;
+    operationId: string;
+    searchType: "auto";
+    requestCount: 1;
+    requestedResultCount: number;
+    returnedResultCount: number | null;
+    pricingStatus: "unpriced";
+    unknownReason: "no_rate_authority";
+    valuationStatus: "unpriced";
+}
+export interface UserUsageDetails {
+    scope: UserUsageScope;
+    range: UserUsageRange;
+    llm: UserLlmUsage[];
+    sandbox: UserSandboxUsage[];
+    webSearch: UserWebSearchUsage[];
+}
+export interface OrganizationUserUsageSummary {
+    range: BillingUsageSeriesRange;
+    factCompleteness: BillingFactCompleteness;
+    totals: UsageTotals;
+    llm: {
+        aggregates: LlmUsageAggregate[];
+    };
+    sandbox: {
+        aggregates: SandboxUsageAggregate[];
+    };
+    webSearch: {
+        aggregates: WebSearchUsageAggregate[];
+    };
+    series: BillingUsageSeriesPoint[];
+}
+interface OrganizationUsageCommon {
+    id: string;
+    occurredAt: string;
+    sessionId: string;
+    /** Null only when `kind=llm` and `requestPurpose=voice_realtime`. */
+    turnId: string | null;
+    /** The Realtime connection of `voice_realtime` usage; null otherwise. */
+    realtimeConnectionId?: string | null;
+    agentRunId: string | null;
+    agentId: string | null;
+    attributionKind: BillingAttributionKind;
+    costMicros: number | null;
+    currency: string | null;
+    pricingVersion: string;
+    pricingEffectiveAt: string;
+    valuationStatus: BillingValuationStatus;
+    valuationReason: string | null;
+    rateCardDigest: string | null;
+    billingTag: BillingTag | null;
+}
+export interface OrganizationLlmUsage extends OrganizationUsageCommon {
+    kind: "llm";
+    realtimeConnectionId: string | null;
+    operationId: string | null;
+    requestPurpose: BillingLlmRequestPurpose;
+    provider: string;
+    model: string;
+    observedResponseModel: string | null;
+    inputTokens: number;
+    cachedInputTokens: number;
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    cacheWriteUnspecifiedTokens: number;
+    outputTokens: number;
+    inputCostMicros: number | null;
+    cachedInputCostMicros: number | null;
+    cacheWrite5mCostMicros: number | null;
+    cacheWrite1hCostMicros: number | null;
+    cacheWriteUnspecifiedCostMicros: number | null;
+    outputCostMicros: number | null;
+    pricingStatus: LlmPricingStatus;
+    estimateBasis: "public_list_placeholder" | "contract" | null;
+    contextTier: LlmPricingContextTier;
+}
+export interface OrganizationSandboxUsage extends OrganizationUsageCommon {
+    kind: "sandbox";
+    turnId: string;
+    provider: "e2b" | "tencent_ags" | "run9";
+    profileId: string;
+    specKey: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationSeconds: number | null;
+    status: SandboxUsageStatus;
+}
+export interface OrganizationWebSearchUsage extends OrganizationUsageCommon {
+    kind: "web_search";
+    turnId: string;
+    operationId: string;
+    provider: "exa";
+    searchType: "auto";
+    requestCount: 1;
+    requestedResultCount: number;
+    returnedResultCount: number | null;
+    contentTextRequested: true;
+    requestOutcome: "succeeded" | "failed" | "aborted";
+    usageEvidenceStatus: BillingUsageEvidenceStatus;
+}
+export type OrganizationUsageItem = OrganizationLlmUsage | OrganizationSandboxUsage | OrganizationWebSearchUsage;
+export interface OrganizationUserUsageDetails {
+    items: OrganizationUsageItem[];
+    nextCursor: string | null;
+    factCompleteness: BillingFactCompleteness;
+}
+export interface UserUsageOptions extends RequestOptions {
+    period?: "day" | "week";
+    /** Inclusive UTC date, YYYY-MM-DD. */
+    from?: string;
+    /** Inclusive UTC date, YYYY-MM-DD. */
+    to?: string;
+    tagKey?: string;
+    tagValue?: string;
+}
+export interface UserUsageDetailsOptions extends UserUsageOptions {
+    /** Maximum rows per kind, 1-500; this endpoint has no continuation cursor. */
+    limit?: number;
+}
+export interface OrganizationUserUsageOptions extends RequestOptions {
+    /** Exact inclusive UTC timestamp with milliseconds; maximum range is 31 days. */
+    from: string;
+    /** Exact exclusive UTC timestamp with milliseconds. */
+    to: string;
+    interval?: BillingUsageSeriesInterval;
+    tagKey?: string;
+    tagValue?: string;
+}
+export interface OrganizationUserUsageDetailsOptions extends Omit<OrganizationUserUsageOptions, "interval"> {
+    kind?: BillingUsageFactKind;
+    limit?: number;
+    cursor?: string;
+}
+export declare const usageQuery: (options: object, allowed: readonly string[]) => string;
+export declare const userUsagePath: (userId: string, options: {
+    from: string;
+    to: string;
+}) => string;
+export {};
+//# sourceMappingURL=usage.d.ts.map