@byte_fluffy/nexra-sdk 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,1006 @@
+import { J as JsonObject, B as BillingMetric, a as JsonValue, N as NexraSettlement, C as CursorPage, H as HttpTransport, M as ModelSearchParams, T as TaskModelSummary, b as TaskModel, c as ModelSchema, d as CatalogClient, e as NexraClientOptions } from './catalog-mytCeh5t.js';
+export { f as BILLING_EXPORT_DIMENSIONS, g as BILLING_METRICS, h as CreateNexraQuoteRequest, F as FetchLike, i as JsonPrimitive, j as MeteredPriceRate, k as MeteredPriceRuleV1, l as MeteredUsageComponent, m as MeteringContract, n as MeteringKind, o as ModelCapabilitySummary, p as ModelDateVersion, q as ModelEndpointSummary, r as ModelModality, s as ModelResourceList, t as ModelResourceOption, u as NexraBillingCurrency, v as NexraModelOperation, w as NexraModelSpec, x as NexraModelSpecFilter, y as NexraQuote, z as NexraSalePrice, A as NormalizedUsageV1, P as PriceEvaluation, D as PriceEvaluationIssue, E as PriceEvaluationLine, G as PriceRule, U as UsageComponentEvidence, I as UsageEvidenceAssessment, K as UsageEvidenceStatus, L as allocateDiscountedPriceLines, O as assessUsageEvidence, Q as evaluatePriceRule, R as getModelSpec, S as jsonBody, V as listModelSpecs, W as queryString, X as sleep, Y as validateMeteringContract, Z as validateNormalizedUsage, _ as validatePriceRule } from './catalog-mytCeh5t.js';
+export { ceilDecimal, multiplyDecimal } from './decimal.js';
+
+declare const MEDIA_KINDS: readonly ["image", "video", "audio", "document", "archive", "other"];
+type MediaKind = (typeof MEDIA_KINDS)[number];
+type MediaAssetStatus = "pending" | "ready" | "failed" | "deleted";
+interface MediaAsset {
+    id: string;
+    kind: MediaKind;
+    status: MediaAssetStatus;
+    source: "upload" | "generated" | "provider" | "imported";
+    name?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    checksumSha256?: string;
+    url?: string;
+    downloadUrl?: string;
+    expiresAt?: string;
+    metadata?: JsonObject;
+    createdAt: string;
+}
+interface AssetReference {
+    assetId: string;
+}
+type AssetInput = AssetReference | Blob | File | MediaAsset | string | URL;
+interface AssetUploadOptions {
+    kind?: MediaKind;
+    name?: string;
+    signal?: AbortSignal;
+}
+interface AssetImportRequest {
+    url: string;
+    kind?: MediaKind;
+    name?: string;
+}
+
+type UploadDeliveryRegion = "cn" | "global";
+declare function modelUploadRegion(regions: readonly string[]): UploadDeliveryRegion;
+declare function uploadedMediaUrl(value: string, region: UploadDeliveryRegion): string;
+declare function uploadedMediaInput(input: JsonObject, region: UploadDeliveryRegion): JsonObject;
+
+/**
+ * Frozen usage-reporting semantics (admin-console-status TODO-01).
+ *
+ * Time: the population axis is `gateway.requests.received_at` and every
+ * window is the half-open interval `[start, end)`. The database stores UTC
+ * instants; API callers pass ISO-8601 instants and may pass a
+ * `timeZoneOffsetMinutes` offset (east positive, -720..840) that only affects
+ * day/month/… bucket edges, never stored data or window matching.
+ *
+ * Sources: a request may carry several usage records (unique per source).
+ * Reporting reads exactly one per request with the fixed priority
+ * `reconciled` > `provider` > `estimated`; `reconciled` is the final truth
+ * after correction, `provider` is vendor evidence, `estimated` is a fallback.
+ *
+ * Normalization status (derived at query time, there is no stored column):
+ * - `normalized`: the selected record has a valid non-empty v1 component array.
+ * - `partial`: reserved for "some raw vendor fields could not be mapped into
+ *   any standard metric"; the current pipeline cannot detect it, so queries
+ *   never emit it yet but callers may already filter for it.
+ * - `invalid`: a record exists but the normalized envelope is unusable
+ *   (missing/non-array/empty components).
+ * - `missing`: no usage record exists for the request.
+ *
+ * Rating status (derived from the highest-priority charge of the request):
+ * - `billed`: a succeeded or refunded charge exists.
+ * - `billing_failed`: the chosen charge failed.
+ * - `unsettled`: usage exists, no charge yet, and a published sale price
+ *   version effective at usage time exists (or the request has not
+ *   succeeded, so settlement is not expected yet).
+ * - `unpriced`: usage exists, no charge, request succeeded, and no published
+ *   sale price version was effective at usage time for the model/operation.
+ * - `usage_missing`: no usage record, so rating is impossible.
+ *
+ * "不适用 / 0 / 缺失" stay distinct: a metric absent from `metrics` means
+ * nothing was metered (missing or not applicable); a present `0` value was
+ * genuinely metered as zero. `tokens.applicable = false` means the model has
+ * no token rate in any published sale/cost price version, so empty token
+ * metrics for such models are "not applicable", never "missing".
+ */
+declare const USAGE_SOURCES: readonly ["provider", "estimated", "reconciled"];
+type UsageSource = (typeof USAGE_SOURCES)[number];
+declare const USAGE_NORMALIZATION_STATUSES: readonly ["normalized", "partial", "invalid", "missing"];
+type UsageNormalizationStatus = (typeof USAGE_NORMALIZATION_STATUSES)[number];
+declare const USAGE_RATING_STATUSES: readonly ["billed", "unsettled", "billing_failed", "unpriced", "usage_missing"];
+type UsageRatingStatus = (typeof USAGE_RATING_STATUSES)[number];
+declare const USAGE_GROUP_BYS: readonly ["minute", "hour", "day", "month", "user", "apiKey", "provider", "channel", "model", "operation"];
+type UsageGroupBy = (typeof USAGE_GROUP_BYS)[number];
+declare const USAGE_AMOUNT_KINDS: readonly ["sale", "cost", "gross"];
+type UsageAmountKind = (typeof USAGE_AMOUNT_KINDS)[number];
+declare const TOKEN_METRICS: readonly ["input_tokens", "cached_input_tokens", "cache_write_tokens", "cache_creation_5m_input_tokens", "cache_creation_1h_input_tokens", "cache_read_input_tokens", "output_tokens"];
+/** Decimal string with up to 8 fraction digits; only `gross` may be negative. */
+declare const MONEY_STRING_PATTERN: RegExp;
+type MoneyString = string;
+interface UsageTimeWindow {
+    /** Inclusive ISO-8601 instant. */
+    start: string;
+    /** Exclusive ISO-8601 instant; must be after `start`. */
+    end: string;
+}
+interface UsageFilters extends UsageTimeWindow {
+    timeZoneOffsetMinutes?: number;
+    userIds?: string[];
+    apiKeyIds?: string[];
+    providerIds?: string[];
+    channelIds?: string[];
+    modelIds?: string[];
+    operations?: string[];
+    upstreamModelId?: string;
+    requestStatuses?: string[];
+    usageSources?: UsageSource[];
+    normalizationStatuses?: UsageNormalizationStatus[];
+    ratingStatuses?: UsageRatingStatus[];
+}
+interface UsageSummaryQuery {
+    filters: UsageFilters;
+    /** At most one time granularity; keys are ordered as given. */
+    groupBy: UsageGroupBy[];
+    limit: number;
+    cursor?: string;
+}
+interface UsageSummaryGroup {
+    /** Bucket start as a UTC instant; present for time granularities. */
+    time?: string;
+    userId?: string | null;
+    apiKeyId?: string | null;
+    providerId?: string | null;
+    channelId?: string | null;
+    modelId?: string | null;
+    operation?: string | null;
+}
+interface UsageSummaryAmount {
+    kind: UsageAmountKind;
+    currency: string;
+    /** Decimal string; sums of numeric(20,8) charge amounts. */
+    amount: MoneyString;
+}
+interface UsageSummaryRow {
+    group: UsageSummaryGroup;
+    requests: {
+        total: number;
+        succeeded: number;
+        /** failed + cancelled + rejected requests. */
+        failed: number;
+    };
+    usage: {
+        /** Requests whose prioritized usage record exists. */
+        evidence: number;
+        /** Requests without any usage record; equals rating.usage_missing. */
+        missing: number;
+        sources: Record<UsageSource, number>;
+        normalization: Record<Exclude<UsageNormalizationStatus, "missing">, number>;
+    };
+    rating: Record<UsageRatingStatus, number>;
+    costReporting: {
+        /** Succeeded charges with a CNY reporting cost. */
+        reported: number;
+        /** Succeeded charges whose procurement cost was not recorded. */
+        missingCost: number;
+        /** Succeeded charges with an original cost but no matching frozen FX rate. */
+        missingRate: number;
+    };
+    tokens: {
+        /** Null unless `model` is a group key. */
+        applicable: boolean | null;
+        requestsWithTokenMetrics: number;
+    };
+    /** Metric quantities summed across dimensions; absent keys were never metered. */
+    metrics: Partial<Record<BillingMetric, number>>;
+    amounts: UsageSummaryAmount[];
+}
+interface UsageSummaryPage {
+    data: UsageSummaryRow[];
+    /** Present when more groups follow; opaque, valid only for the same query. */
+    nextCursor: string | null;
+}
+declare const USAGE_FILTER_SELECTION_LIMIT = 200;
+declare function validateUsageFilters(value: unknown): asserts value is UsageFilters;
+declare function validateUsageSummaryQuery(value: unknown): asserts value is UsageSummaryQuery;
+/** Cursors are opaque offsets; they are only valid for the identical query. */
+declare function encodeUsageSummaryCursor(offset: number): string;
+declare function parseUsageSummaryCursor(value: string): number | null;
+/**
+ * Keyset cursor over `(received_at, request id)` in descending order, shared
+ * by the details and anomaly queries.
+ */
+declare function encodeUsageKeysetCursor(receivedAt: string, requestId: string): string;
+declare function parseUsageKeysetCursor(value: string): {
+    receivedAt: string;
+    requestId: string;
+} | null;
+interface UsageDetailsQuery {
+    filters: UsageFilters;
+    /** Page size, 1..200. */
+    limit: number;
+    cursor?: string;
+}
+interface UsageDetailUsage {
+    id: string | null;
+    source: UsageSource | null;
+    occurredAt: string | null;
+    /** Vendor-native evidence; request/response bodies and credentials are excluded. */
+    rawUsage: JsonObject;
+    normalizedUsage: JsonObject;
+    normalizationStatus: UsageNormalizationStatus;
+}
+interface UsageDetailCharge {
+    id: string;
+    status: string;
+    saleAmount: MoneyString | null;
+    saleCurrency: string | null;
+    costAmount: MoneyString | null;
+    costCurrency: string | null;
+    costReportingAmount: MoneyString | null;
+    costReportingCurrency: string | null;
+    costReportingFxRate: MoneyString | null;
+    costReportingFxSource: string | null;
+    costReportingFxEffectiveAt: string | null;
+    /** Price revision numbers bound at settlement time. */
+    discountBps: number | null;
+    /** Settlement-time price evaluation snapshot, including its `lines` and `issues`. */
+    breakdown: JsonObject;
+}
+interface UsageDetailRow {
+    /** Database request id; the drill-down key. */
+    requestId: string;
+    /** Client-facing request key (`gateway.requests.request_id`). */
+    requestKey: string;
+    receivedAt: string;
+    status: string;
+    httpStatus: number | null;
+    durationMs: number | null;
+    errorCode: string | null;
+    userId: string | null;
+    apiKeyId: string | null;
+    modelId: string;
+    modelPublicId: string | null;
+    requestedModel: string | null;
+    operation: string | null;
+    publicProtocol: string | null;
+    providerId: string | null;
+    channelId: string | null;
+    upstreamModelId: string | null;
+    usage: UsageDetailUsage;
+    ratingStatus: UsageRatingStatus;
+    charge: UsageDetailCharge | null;
+}
+interface UsageDetailsPage {
+    data: UsageDetailRow[];
+    nextCursor: string | null;
+}
+declare function validateUsageDetailsQuery(value: unknown): asserts value is UsageDetailsQuery;
+/**
+ * Mutually exclusive anomaly buckets; every request lands in at most one,
+ * first match wins (settlement_failed > normalization_failed > unpriced >
+ * usage_missing > dimension_mismatch). Note that `usage_missing` only covers
+ * succeeded requests — failed requests without usage never expected billing —
+ * so its count can differ from the summary's `rating.usage_missing`, which
+ * has no request-status restriction.
+ */
+declare const USAGE_ANOMALY_CATEGORIES: readonly ["usage_missing", "normalization_failed", "unpriced", "dimension_mismatch", "settlement_failed"];
+type UsageAnomalyCategory = (typeof USAGE_ANOMALY_CATEGORIES)[number];
+interface UsageAnomaliesQuery {
+    filters: UsageFilters;
+    categories?: UsageAnomalyCategory[];
+    /** Page size, 1..200. */
+    limit: number;
+    cursor?: string;
+}
+interface UsageAnomalyRow {
+    category: UsageAnomalyCategory;
+    /** Database request id; drill down via the details query. */
+    requestId: string;
+    requestKey: string;
+    receivedAt: string;
+    userId: string | null;
+    modelId: string;
+    modelPublicId: string | null;
+    providerId: string | null;
+    channelId: string | null;
+    upstreamModelId: string | null;
+    /** Cause codes, e.g. charge error code or evaluation issue codes. */
+    reason: string;
+    /**
+     * True when the money impact is quantifiable from stored charge amounts
+     * (settlement_failed, dimension_mismatch, and billed normalization_failed
+     * cases carry a sale amount).
+     */
+    amountKnown: boolean;
+}
+interface UsageAnomaliesPage {
+    data: UsageAnomalyRow[];
+    nextCursor: string | null;
+}
+interface UsageAnomalySummaryQuery {
+    filters: UsageFilters;
+    /** Optional per-category breakdowns; each adds one grouped aggregate. */
+    breakdowns?: Array<"provider" | "channel" | "model">;
+}
+interface UsageAnomalySummaryRow {
+    category: UsageAnomalyCategory;
+    count: number;
+    firstOccurredAt: string;
+    lastOccurredAt: string;
+}
+interface UsageAnomalyBreakdownRow {
+    category: UsageAnomalyCategory;
+    dimension: "provider" | "channel" | "model";
+    dimensionId: string | null;
+    count: number;
+}
+interface UsageAnomalySummaryPage {
+    categories: UsageAnomalySummaryRow[];
+    breakdowns: UsageAnomalyBreakdownRow[];
+}
+declare function validateUsageAnomaliesQuery(value: unknown): asserts value is UsageAnomaliesQuery;
+declare function validateUsageAnomalySummaryQuery(value: unknown): asserts value is UsageAnomalySummaryQuery;
+
+declare const ADMIN_USER_ROLES: readonly ["admin", "dealer", "user"];
+type AdminUserRole = (typeof ADMIN_USER_ROLES)[number];
+declare const ADMIN_USER_STATUSES: readonly ["active", "banned"];
+type AdminUserStatus = (typeof ADMIN_USER_STATUSES)[number];
+interface AdminUserListQuery {
+    /** Matches email, name, or exact user id. */
+    query?: string;
+    role?: AdminUserRole;
+    status?: AdminUserStatus;
+    /** Page size, 1..200. */
+    limit: number;
+    cursor?: string;
+}
+interface AdminUserWalletSummary {
+    currency: string;
+    balance: MoneyString;
+    reservedBalance: MoneyString;
+    status: string;
+}
+interface AdminUserSummaryRow {
+    userId: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    role: string;
+    status: string;
+    qpsLimit: number;
+    createdAt: string;
+    /** Non-revoked, unexpired API keys. */
+    keyCount: number;
+    wallets: AdminUserWalletSummary[];
+    lastKeyUsedAt: string | null;
+    usageLast30Days: {
+        /** Backend snapshot window; absent only on older API versions. */
+        windowStart?: string;
+        windowEnd?: string;
+        requests: number;
+        /** Settled sale amounts per currency over the same 30 days. */
+        saleByCurrency: Record<string, MoneyString>;
+    };
+}
+interface AdminUserKeyRow {
+    id: string;
+    name: string;
+    prefix: string;
+    lastFour: string;
+    /** Derived: revoked > expired > active. */
+    status: "active" | "revoked" | "expired";
+    createdAt: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
+    rateLimitPerSecond: number | null;
+}
+interface AdminUserDiscountRow {
+    id: string;
+    modelId: string;
+    modelPublicId: string | null;
+    operation: string;
+    /** Basis points off the public sale price; 2000 = 20% off. */
+    discountBps: number;
+    status: string;
+    effectiveFrom: string;
+    effectiveTo: string | null;
+    note: string | null;
+}
+interface AdminUserPricingAdjustmentRow {
+    id: string;
+    /** "user" rules apply to every key of the user; "api_key" rules win over them. */
+    subjectType: "user" | "api_key";
+    apiKeyId: string | null;
+    keyName: string | null;
+    keyHint: string | null;
+    modelId: string | null;
+    modelPublicId: string | null;
+    operation: string | null;
+    /** Positive decimal multiplier applied to the standard sale price; 1.0000 = unchanged. */
+    multiplier: string;
+    status: string;
+    effectiveFrom: string;
+    effectiveTo: string | null;
+    note: string | null;
+}
+interface AdminUserDetail extends AdminUserSummaryRow {
+    keys: AdminUserKeyRow[];
+    discounts: AdminUserDiscountRow[];
+    pricingAdjustments: AdminUserPricingAdjustmentRow[];
+}
+interface AdminUserListPage {
+    data: AdminUserSummaryRow[];
+    /** Present when more users follow; opaque, valid only for the same query. */
+    nextCursor: string | null;
+}
+interface AdminUserListCursor {
+    createdAt: string;
+    userId: string;
+}
+declare function validateAdminUserListQuery(value: unknown): asserts value is AdminUserListQuery;
+declare function encodeAdminUserCursor(cursor: AdminUserListCursor): string;
+declare function parseAdminUserCursor(value: string): AdminUserListCursor | null;
+declare const ADMIN_USER_ACTIVITY_KINDS: readonly ["ledger", "recharge", "hold", "audit"];
+type AdminUserActivityKind = (typeof ADMIN_USER_ACTIVITY_KINDS)[number];
+interface AdminUserActivityRow {
+    id: string;
+    kind: AdminUserActivityKind;
+    occurredAt: string;
+    action: string;
+    currency: string | null;
+    amount: MoneyString | null;
+    balanceAfter: MoneyString | null;
+    status: string | null;
+    referenceId: string | null;
+    actorUserId: string | null;
+    reason: string | null;
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+}
+interface AdminUserActivityPage {
+    data: AdminUserActivityRow[];
+    nextCursor: string | null;
+}
+interface AdminUserWalletOpenInput {
+    currency: "CNY" | "USD";
+    reason: string;
+}
+interface AdminUserWalletOpenResult {
+    walletId: string;
+    currency: string;
+    created: boolean;
+}
+declare function isMoneyString(value: string): boolean;
+interface AdminUserUpdate {
+    role?: AdminUserRole;
+    status?: AdminUserStatus;
+    qpsLimit?: number;
+    /** Required; stored verbatim on the admin audit event. */
+    reason: string;
+}
+interface AdminUserUpdateResult {
+    userId: string;
+    role: string;
+    status: string;
+    qpsLimit: number;
+    updatedAt: string;
+}
+declare function validateAdminUserUpdate(value: unknown): asserts value is AdminUserUpdate;
+interface AdminUserApiKeyUpdate {
+    revoked?: boolean;
+    /** New per-second rate limit; `null` clears the limit. */
+    rateLimitPerSecond?: number | null;
+    /** Required; stored verbatim on the admin audit event. */
+    reason: string;
+}
+interface AdminUserApiKeyUpdateResult {
+    id: string;
+    name: string;
+    prefix: string;
+    lastFour: string;
+    status: "active" | "revoked" | "expired";
+    rateLimitPerSecond: number | null;
+    revokedAt: string | null;
+    updatedAt: string;
+}
+declare function validateAdminUserApiKeyUpdate(value: unknown): asserts value is AdminUserApiKeyUpdate;
+interface AdminWalletRechargeInput {
+    userId: string;
+    /** Single user billing currency: CNY. */
+    currency: string;
+    /** Positive decimal amount string, at most 8 fraction digits. */
+    amount: MoneyString;
+    /** External order reference; unique per payment provider "admin". */
+    externalOrderId: string;
+    /** Required; stored verbatim on the admin audit event. */
+    reason: string;
+}
+interface AdminWalletRechargeResult {
+    rechargeId: string;
+    /** Empty when `created` is false (idempotent retry of a known order). */
+    ledgerEntryId: string;
+    walletId: string;
+    currency: string;
+    /** Wallet balance after this operation. */
+    balance: MoneyString;
+    /** False when the external order was already credited; nothing changed. */
+    created: boolean;
+}
+declare function validateAdminWalletRechargeInput(value: unknown): asserts value is AdminWalletRechargeInput;
+
+declare const USAGE_FILTER_KINDS: readonly ["model", "user", "apiKey", "provider", "channel", "operation"];
+type UsageFilterKind = (typeof USAGE_FILTER_KINDS)[number];
+interface UsageFilterOption {
+    id: string;
+    label: string;
+    description: string;
+}
+interface UsageFilterOptionsPage {
+    data: UsageFilterOption[];
+    nextCursor: string | null;
+}
+interface UsageFilterOptionsQuery {
+    limit: number;
+    query?: string;
+    cursor?: string;
+    ids?: string[];
+}
+declare function encodeUsageFilterCursor(kind: UsageFilterKind, query: string, id: string): string;
+declare function parseUsageFilterCursor(value: string, kind: UsageFilterKind, query: string): string | null;
+declare function validateUsageFilterOptionsQuery(kind: UsageFilterKind, value: unknown): asserts value is UsageFilterOptionsQuery;
+
+declare const BILLING_CURRENCY = "CNY";
+declare const WALLET_MAX_BALANCE_UNITS = 99999999999999999999n;
+declare function moneyToUnits(value: string): bigint;
+declare function moneyFromUnits(value: bigint): string;
+declare function multiplyMoney(value: string, multiplier: string, ...additionalMultipliers: string[]): string;
+
+interface ApiErrorPayload {
+    error: {
+        code: string;
+        message: string;
+        category?: string;
+        retryable?: boolean;
+        requestId?: string;
+        details?: JsonObject;
+    };
+}
+
+/** Upgrade old DB snapshots at the read boundary; authored fields carry their own annotations. */
+declare function normalizeModelParameterSchema(source: Readonly<JsonObject>): JsonObject;
+declare function modelInputDefaults(input: JsonObject): JsonObject;
+declare function orderedSchemaProperties(schema: JsonObject): [string, JsonValue][];
+/** Compatibility projection for existing schema API clients, never a second authoring source. */
+declare function modelInputUi(input: JsonObject): JsonObject;
+
+declare const TASK_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelling", "cancelled"];
+type TaskStatus = (typeof TASK_STATUSES)[number];
+type TerminalTaskStatus = "succeeded" | "failed" | "cancelled";
+interface TaskProgress {
+    percent?: number;
+    stage?: string;
+    message?: string;
+}
+interface TaskError {
+    code: string;
+    message: string;
+    category?: string;
+    retryable?: boolean;
+    details?: JsonObject;
+}
+interface TaskUsage {
+    components: Array<{
+        name: string;
+        quantity: number;
+        unit: string;
+    }>;
+    metadata?: JsonObject;
+}
+interface TaskCost {
+    amount: string;
+    currency: string;
+}
+interface TaskTiming {
+    submittedAt: string;
+    providerSubmittedAt?: string;
+    providerCompletedAt?: string;
+    storedAt?: string;
+    preparationMs: number | null;
+    generationMs: number | null;
+    storageMs: number | null;
+    totalMs: number | null;
+    startSource: "client" | "server";
+}
+/** Repository/console read model. HTTP clients receive TaskReceipt or TaskResult. */
+interface Task<TOutput = JsonValue> {
+    id: string;
+    /** Original platform request ID, shared with request history. */
+    requestId?: string;
+    /** Public Run ID, when this Task belongs to a shared-input run. */
+    runId?: string;
+    model: string;
+    operation: string;
+    schemaVersion: number;
+    /** Model request parameters; native-managed tasks retain the upstream field structure. */
+    input?: JsonObject;
+    status: TaskStatus;
+    /** Regional media availability; execution/billing remain terminal while replicas prepare. */
+    deliveryStatus?: "preparing" | "ready";
+    progress?: TaskProgress;
+    /** Native-managed tasks preserve the final response shape and media URLs; catalog models may normalize model identifiers. */
+    output?: TOutput;
+    assets: MediaAsset[];
+    error?: TaskError;
+    usage?: TaskUsage;
+    cost?: TaskCost;
+    /** Customer billing state; absent on older servers. */
+    billingStatus?: "pending" | "succeeded" | "failed" | "refunded" | "unavailable";
+    /** Final customer sale settlement. Provider procurement cost is never exposed here. */
+    settlement?: NexraSettlement;
+    /** Caller-supplied business data, returned unchanged; never sent to the provider. */
+    metadata?: JsonObject;
+    timing?: TaskTiming;
+    /** Server-side Task record creation time (ISO 8601 UTC). */
+    createdAt: string;
+    /** Latest Task record update, not the generation completion time (ISO 8601 UTC). */
+    updatedAt: string;
+    /** First worker execution start; absent while queued or cancelled before execution. */
+    startedAt?: string;
+    /** Terminal succeeded/failed/cancelled time; success follows required asset storage. */
+    completedAt?: string;
+    /** @deprecated Reserved; no Task expiry policy is currently enforced. Not a media URL expiry. */
+    expiresAt?: string;
+}
+/** POST /tasks returns acceptance only, including for idempotent replays. */
+type TaskReceipt = Pick<Task, "id" | "status">;
+/** Public Task result; platform diagnostics and business tags live in RequestDetails. */
+type TaskResult<TOutput = JsonValue> = Pick<Task<TOutput>, "id" | "model" | "status"> & Partial<Pick<Task<TOutput>, "requestId" | "output" | "assets" | "error" | "deliveryStatus" | "settlement">>;
+/** Platform request details, used by both managed Tasks and native proxy requests. */
+interface RequestDetails {
+    id: string;
+    requestId: string;
+    taskId: string | null;
+    method: string;
+    path: string;
+    protocol?: string;
+    accessMode?: string | null;
+    model: string | null;
+    operation: string | null;
+    status: string;
+    httpStatus: number | null;
+    errorCode: string | null;
+    /** HTTP duration, never substituted with asynchronous task duration. */
+    durationMs: number | null;
+    timing?: TaskTiming;
+    cost?: TaskCost;
+    billingStatus?: Task["billingStatus"];
+    settlement?: NexraSettlement;
+    metadata?: JsonObject;
+    /** Latest known execution update; omitted when not observed. */
+    updatedAt?: string;
+    runId?: string;
+    schemaVersion?: number;
+    createdAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    input: JsonObject | null;
+    receivedAt: string;
+    finishedAt: string | null;
+}
+declare function taskReceipt(task: TaskReceipt): TaskReceipt;
+declare function taskResult<TOutput>(task: Task<TOutput>): TaskResult<TOutput>;
+type TaskEventType = "state" | "progress" | "preview" | "log" | "usage" | "warning" | "result";
+interface TaskEvent {
+    id: string;
+    taskId: string;
+    sequence: number;
+    type: TaskEventType;
+    status?: TaskStatus;
+    progress?: TaskProgress;
+    asset?: MediaAsset;
+    message?: string;
+    payload?: JsonObject;
+    occurredAt: string;
+}
+/** @deprecated Use CreateTaskRequest.callback_url. Kept for existing callers. */
+interface TaskWebhookConfig {
+    url: string;
+    /** Shared HMAC secret used to verify Nexra callback signatures. */
+    secret: string;
+    events?: Array<"completed">;
+}
+interface CreateTaskRequest<TInput = Record<string, unknown>> {
+    /** @internal Console telemetry only: browser send time before uploads, not execution time. */
+    submittedAt?: string;
+    model: string;
+    input: TInput;
+    /** Signed Nexra quote used to lock this input to a sale-price revision. */
+    quoteToken?: string;
+    /** Optional business identifiers such as orderId, available in request details. Do not include secrets. */
+    metadata?: JsonObject;
+    /** Platform completion callback, independent of provider callback support. Never sent upstream. */
+    callback_url?: string;
+    /** @deprecated Use callback_url; do not supply both. */
+    webhook?: TaskWebhookConfig;
+    /** @deprecated Compatibility check only; the server resolves the current contract. */
+    schemaVersion?: number;
+}
+/** One user input fanned out to independent durable model Tasks. */
+interface TaskRun<TOutput = JsonValue> {
+    id: string;
+    inputMode: string;
+    input: JsonObject;
+    models: string[];
+    repetitions: number;
+    tasks: Task<TOutput>[];
+    metadata?: JsonObject;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateTaskRunRequest<TInput = Record<string, unknown>> {
+    submittedAt?: string;
+    models: string[];
+    repetitions?: number;
+    inputMode: string;
+    input: TInput;
+    metadata?: JsonObject;
+}
+interface TaskRunListParams {
+    status?: TaskStatus;
+    model?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface TaskListParams {
+    status?: TaskStatus;
+    model?: string;
+    limit?: number;
+    cursor?: string;
+}
+type TaskPage<TOutput = JsonValue> = CursorPage<Task<TOutput>>;
+interface RunResult<TOutput = JsonValue> {
+    taskId: string;
+    output: TOutput;
+    assets: MediaAsset[];
+    usage?: TaskUsage;
+    cost?: TaskCost;
+    task: TaskResult<TOutput>;
+}
+declare function isTerminalTaskStatus(status: TaskStatus): status is TerminalTaskStatus;
+
+type ObservationResult = "success" | "failure" | "excluded" | "rate_limited" | "restricted";
+type AvailabilityBucket = {
+    start: string;
+    end: string;
+    state: "success" | "failure" | "mixed" | "unknown";
+    evidence: "measured" | "carried" | "expired" | "none";
+    businessSuccess: number;
+    businessFailure: number;
+    probeSuccess: number;
+    probeFailure: number;
+    latestAt: string | null;
+    coreSuccess: number;
+    coreFailure: number;
+    expectedSamples: number | null;
+    incomplete: boolean;
+};
+type AvailabilityObservation = {
+    at: string;
+    result: ObservationResult;
+    source: "business" | "probe" | "core";
+    count?: number;
+};
+type AvailabilityStats = {
+    success: number;
+    failure: number;
+    excluded: number;
+    rateLimited: number;
+    restricted: number;
+    rate: number | null;
+};
+type ProbeTargetConfig = {
+    routeId: string;
+    enabled: boolean;
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    templateVersion: number;
+    input: JsonObject;
+    maxUsage?: JsonObject | null;
+    currency: string;
+    maxCost: string;
+};
+type ProbeRunView = {
+    id: string;
+    targetId: string;
+    status: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+    scheduledAt: string;
+    upstreamTaskId: string | null;
+    errorCode: string | null;
+    stage: string | null;
+    durationMs: number | null;
+    currency: string;
+    reservedCost: string;
+    actualCost: string | null;
+    costStatus: string;
+};
+type ProbeTargetView = {
+    id: string;
+    routeId: string;
+    channelId: string;
+    channelName: string;
+    model: string;
+    kind: string;
+    protocol: string;
+    enabled: boolean;
+    readiness: string;
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    templateVersion: number;
+    input: JsonObject;
+    maxUsage?: JsonObject | null;
+    currency: string | null;
+    maxCost: string | null;
+    nextAt: string | null;
+    business: AvailabilityStats;
+    probes: AvailabilityStats;
+    buckets: AvailabilityBucket[];
+    latestRun: ProbeRunView | null;
+};
+type AdminOverview = {
+    generatedAt: string;
+    window: {
+        start: string;
+        end: string;
+        hours: number;
+    };
+    complete: boolean;
+    summary: {
+        models: number;
+        channels: number;
+        tasks24h: number;
+        tasksSucceeded24h: number;
+        tasksFailed24h: number;
+        tasksCancelled24h: number;
+        taskSuccessRate: number | null;
+        requests5m: number;
+        errors5m: number;
+        qps: number;
+        p95Ms: number | null;
+        p99Ms: number | null;
+        latencySamples: number;
+        requestSuccessRate: number | null;
+        requestSamples: number;
+    };
+    callbacks: {
+        pending: number;
+        retrying: number;
+        failed: number;
+        delivered24h: number;
+    };
+    core: {
+        id: string;
+        name: string;
+        buckets: AvailabilityBucket[];
+        latestAt: string | null;
+    }[];
+    requests: {
+        id: string;
+        model: string | null;
+        path: string;
+        status: string;
+        httpStatus: number | null;
+        durationMs: number | null;
+        at: string;
+        taskId?: string | null;
+        taskDurationMs?: number | null;
+        taskStatus?: string | null;
+        taskSubmittedAt?: string | null;
+        taskCreatedAt?: string | null;
+    }[];
+    tasks: {
+        id: string;
+        model: string;
+        status: string;
+        phase: string | null;
+        startedAt: string | null;
+        createdAt: string;
+        submittedAt?: string | null;
+    }[];
+    targets: ProbeTargetView[];
+    budgets: {
+        currency: string;
+        dailyLimit: string;
+        reserved: string;
+        settled: string;
+    }[];
+};
+declare function defaultProbeInterval(kind: string, model: string): number;
+declare function defaultProbeTimeout(kind: string): number;
+declare function classifyObservation(status: string, httpStatus: number | null, code?: string): ObservationResult;
+declare function availabilityStats(items: readonly AvailabilityObservation[]): AvailabilityStats;
+/** Buckets carry evidence forward only. Carried states never create observations. */
+declare function availabilityBuckets(items: readonly AvailabilityObservation[], end: Date, hours: number, intervalSeconds: number, core?: boolean): AvailabilityBucket[];
+/** Missing primary meters are unknown, not zero. Optional cache/tool meters need not occur. */
+declare function rateProbeUsage(price: unknown, usage: JsonObject | undefined): string | undefined;
+declare function probeCostExceeds(actual: string, limit: string): boolean;
+
+declare class AssetsClient {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    upload(file: Blob, options?: AssetUploadOptions): Promise<MediaAsset>;
+    import(request: AssetImportRequest, signal?: AbortSignal): Promise<MediaAsset>;
+    get(assetId: string, signal?: AbortSignal): Promise<MediaAsset>;
+    download(asset: MediaAsset | string, signal?: AbortSignal): Promise<Response>;
+    stream(asset: MediaAsset | string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+}
+
+declare class ModelsClient {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    search(params?: ModelSearchParams, signal?: AbortSignal): Promise<CursorPage<TaskModelSummary>>;
+    get(model: string, signal?: AbortSignal): Promise<TaskModel>;
+    schema(model: string, signal?: AbortSignal): Promise<ModelSchema>;
+}
+
+interface CreateTaskOptions<TInput = Record<string, unknown>> {
+    input: TInput;
+    quoteToken?: string;
+    submittedAt?: string;
+    metadata?: JsonObject;
+    callback_url?: string;
+    /** @deprecated Use callback_url; do not supply both. */
+    webhook?: TaskWebhookConfig;
+    schemaVersion?: number;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+interface WatchTaskOptions {
+    signal?: AbortSignal;
+    lastEventId?: string;
+    maxReconnects?: number;
+}
+interface WaitTaskOptions extends WatchTaskOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onEvent?: (event: TaskEvent) => void | Promise<void>;
+}
+interface RunTaskOptions<TInput = Record<string, unknown>> extends CreateTaskOptions<TInput>, WaitTaskOptions {
+    cancelOnAbort?: boolean;
+}
+declare class TasksClient {
+    private readonly transport;
+    private readonly assets;
+    constructor(transport: HttpTransport, assets: AssetsClient);
+    create<TOutput = JsonValue, TInput = Record<string, unknown>>(model: string, options: CreateTaskOptions<TInput>): Promise<TaskReceipt>;
+    get<TOutput = JsonValue>(taskId: string, signal?: AbortSignal): Promise<TaskResult<TOutput>>;
+    list<TOutput = JsonValue>(params?: TaskListParams, signal?: AbortSignal): Promise<CursorPage<TaskResult<TOutput>>>;
+    cancel<TOutput = JsonValue>(taskId: string, signal?: AbortSignal): Promise<TaskReceipt>;
+    watch(taskId: string, options?: WatchTaskOptions): AsyncGenerator<TaskEvent>;
+    wait<TOutput = JsonValue>(taskId: string, options?: WaitTaskOptions): Promise<TaskResult<TOutput>>;
+    run<TOutput = JsonValue, TInput = Record<string, unknown>>(model: string, options: RunTaskOptions<TInput>): Promise<RunResult<TOutput>>;
+}
+
+declare class NexraClient {
+    readonly assets: AssetsClient;
+    readonly catalog: CatalogClient;
+    readonly models: ModelsClient;
+    readonly tasks: TasksClient;
+    constructor(options?: NexraClientOptions);
+    run<TOutput = JsonValue, TInput = Record<string, unknown>>(model: string, options: RunTaskOptions<TInput>): Promise<RunResult<TOutput>>;
+}
+declare function createNexra(options?: NexraClientOptions): NexraClient;
+
+declare class NexraApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    readonly details?: ApiErrorPayload["error"]["details"];
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        requestId?: string;
+        retryable?: boolean;
+        details?: ApiErrorPayload["error"]["details"];
+    });
+}
+declare class NexraTaskError extends Error {
+    readonly task: TaskResult<unknown>;
+    constructor(task: TaskResult<unknown>);
+}
+declare class NexraWaitTimeoutError extends Error {
+    readonly taskId: string;
+    readonly timeoutMs: number;
+    constructor(taskId: string, timeoutMs: number);
+}
+
+interface VerifyWebhookOptions {
+    toleranceSeconds?: number;
+    now?: Date;
+}
+/** @deprecated Only verifies legacy signed webhooks, not callback_url notifications. */
+declare function verifyWebhook(request: Request, secret: string, options?: VerifyWebhookOptions): Promise<boolean>;
+
+export { ADMIN_USER_ACTIVITY_KINDS, ADMIN_USER_ROLES, ADMIN_USER_STATUSES, type AdminOverview, type AdminUserActivityKind, type AdminUserActivityPage, type AdminUserActivityRow, type AdminUserApiKeyUpdate, type AdminUserApiKeyUpdateResult, type AdminUserDetail, type AdminUserDiscountRow, type AdminUserKeyRow, type AdminUserListCursor, type AdminUserListPage, type AdminUserListQuery, type AdminUserPricingAdjustmentRow, type AdminUserRole, type AdminUserStatus, type AdminUserSummaryRow, type AdminUserUpdate, type AdminUserUpdateResult, type AdminUserWalletOpenInput, type AdminUserWalletOpenResult, type AdminUserWalletSummary, type AdminWalletRechargeInput, type AdminWalletRechargeResult, type ApiErrorPayload, type AssetImportRequest, type AssetInput, type AssetReference, type AssetUploadOptions, AssetsClient, type AvailabilityBucket, type AvailabilityObservation, type AvailabilityStats, BILLING_CURRENCY, BillingMetric, CatalogClient, type CreateTaskOptions, type CreateTaskRequest, type CreateTaskRunRequest, CursorPage, HttpTransport, JsonObject, JsonValue, MEDIA_KINDS, MONEY_STRING_PATTERN, type MediaAsset, type MediaAssetStatus, type MediaKind, ModelSchema, ModelSearchParams, ModelsClient, type MoneyString, NexraApiError, NexraClient, NexraClientOptions, NexraSettlement, NexraTaskError, NexraWaitTimeoutError, type ObservationResult, type ProbeRunView, type ProbeTargetConfig, type ProbeTargetView, type RequestDetails, type RunResult, type RunTaskOptions, TASK_STATUSES, TOKEN_METRICS, type Task, type TaskCost, type TaskError, type TaskEvent, type TaskEventType, type TaskListParams, TaskModel, TaskModelSummary, type TaskPage, type TaskProgress, type TaskReceipt, type TaskResult, type TaskRun, type TaskRunListParams, type TaskStatus, type TaskTiming, type TaskUsage, type TaskWebhookConfig, TasksClient, type TerminalTaskStatus, USAGE_AMOUNT_KINDS, USAGE_ANOMALY_CATEGORIES, USAGE_FILTER_KINDS, USAGE_FILTER_SELECTION_LIMIT, USAGE_GROUP_BYS, USAGE_NORMALIZATION_STATUSES, USAGE_RATING_STATUSES, USAGE_SOURCES, type UploadDeliveryRegion, type UsageAmountKind, type UsageAnomaliesPage, type UsageAnomaliesQuery, type UsageAnomalyBreakdownRow, type UsageAnomalyCategory, type UsageAnomalyRow, type UsageAnomalySummaryPage, type UsageAnomalySummaryQuery, type UsageAnomalySummaryRow, type UsageDetailCharge, type UsageDetailRow, type UsageDetailUsage, type UsageDetailsPage, type UsageDetailsQuery, type UsageFilterKind, type UsageFilterOption, type UsageFilterOptionsPage, type UsageFilterOptionsQuery, type UsageFilters, type UsageGroupBy, type UsageNormalizationStatus, type UsageRatingStatus, type UsageSource, type UsageSummaryAmount, type UsageSummaryGroup, type UsageSummaryPage, type UsageSummaryQuery, type UsageSummaryRow, type UsageTimeWindow, type VerifyWebhookOptions, WALLET_MAX_BALANCE_UNITS, type WaitTaskOptions, type WatchTaskOptions, availabilityBuckets, availabilityStats, classifyObservation, createNexra, defaultProbeInterval, defaultProbeTimeout, encodeAdminUserCursor, encodeUsageFilterCursor, encodeUsageKeysetCursor, encodeUsageSummaryCursor, isMoneyString, isTerminalTaskStatus, modelInputDefaults, modelInputUi, modelUploadRegion, moneyFromUnits, moneyToUnits, multiplyMoney, normalizeModelParameterSchema, orderedSchemaProperties, parseAdminUserCursor, parseUsageFilterCursor, parseUsageKeysetCursor, parseUsageSummaryCursor, probeCostExceeds, rateProbeUsage, taskReceipt, taskResult, uploadedMediaInput, uploadedMediaUrl, validateAdminUserApiKeyUpdate, validateAdminUserListQuery, validateAdminUserUpdate, validateAdminWalletRechargeInput, validateUsageAnomaliesQuery, validateUsageAnomalySummaryQuery, validateUsageDetailsQuery, validateUsageFilterOptionsQuery, validateUsageFilters, validateUsageSummaryQuery, verifyWebhook };