@byte_fluffy/nexra-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,35 @@
+# @byte_fluffy/nexra-sdk
+
+TypeScript SDK for the Nexra Task API. It includes task execution, model discovery,
+asset upload/download, webhook verification, authoritative catalog quotes, and the
+browser-safe public model catalog.
+
+```bash
+npm install @byte_fluffy/nexra-sdk@next
+```
+
+```ts
+import { createNexra, getModelSpec } from "@byte_fluffy/nexra-sdk";
+
+const nexra = createNexra({ apiKey: process.env.NEXRA_API_KEY });
+const spec = getModelSpec("gpt-image-2");
+const input = {
+  model: spec!.id,
+  prompt: "A paper boat on a blue table",
+  size: "1024x1024",
+  quality: "medium",
+};
+const quote = await nexra.catalog.quote({
+  modelId: spec!.id,
+  operation: "image.generate",
+  input,
+});
+const result = await nexra.run(spec!.id, { input, quoteToken: quote.quoteToken });
+```
+
+The default API base URL is `https://api.nexra-ai.com/v1`. When overriding
+`baseUrl`, include the `/v1` API prefix.
+
+Static catalog APIs are also available from `@byte_fluffy/nexra-sdk/catalog`.
+Exact non-negative decimal helpers are available from
+`@byte_fluffy/nexra-sdk/decimal`.

package/dist/catalog-mytCeh5t.d.ts

@@ -0,0 +1,313 @@
+type JsonPrimitive = boolean | number | string | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+interface CursorPage<T> {
+    data: T[];
+    nextCursor?: string;
+}
+
+declare const BILLING_METRICS: readonly ["requests", "input_tokens", "cached_input_tokens", "cache_write_tokens", "cache_creation_5m_input_tokens", "cache_creation_1h_input_tokens", "cache_read_input_tokens", "output_tokens", "input_characters", "input_utf8_bytes", "input_images", "output_images", "input_audio_seconds", "output_audio_seconds", "input_video_seconds", "output_video_seconds", "provider_credits", "web_search_requests"];
+type BillingMetric = (typeof BILLING_METRICS)[number];
+declare const BILLING_EXPORT_DIMENSIONS: readonly ["resolution", "duration", "layer_decomposition", "with_audio", "has_input_video", "hd", "prompt_extend", "modality", "tier", "quality", "image_count", "input_token_tier", "input_modality", "service_tier", "inference_geo", "speed", "region_scope", "has_reference_image", "mode"];
+type UsageComponentEvidence = {
+    source: "provider_native" | "request_derived" | "response_derived" | "tariff_equivalent" | "unknown";
+    paths?: string[];
+    calculation?: string;
+};
+interface MeteredUsageComponent {
+    metric: BillingMetric;
+    quantity: number;
+    dimensions?: Record<string, JsonPrimitive>;
+    evidence?: UsageComponentEvidence;
+}
+/**
+ * Provider evidence is normalized into independent metered components instead
+ * of one canonical model response. This keeps protocol conversion separate
+ * from billing and allows one request to carry differently-dimensioned usage.
+ */
+interface NormalizedUsageV1 {
+    schemaVersion: 1;
+    components: MeteredUsageComponent[];
+    billingEvidenceComplete?: boolean;
+}
+interface MeteredPriceRate {
+    metric: BillingMetric;
+    unitSize: number;
+    unitPrice: string;
+    rounding: "proportional" | "ceil";
+    includedQuantity?: number;
+    dimensions?: Record<string, JsonPrimitive>;
+}
+interface MeteredPriceRuleV1 {
+    schemaVersion: 1;
+    type: "metered";
+    rates: MeteredPriceRate[];
+}
+type PriceRule = MeteredPriceRuleV1;
+interface PriceEvaluationLine {
+    evidence?: UsageComponentEvidence;
+    metric: BillingMetric;
+    quantity: number;
+    unitSize: number;
+    unitPrice: string;
+    rounding: "proportional" | "ceil";
+    includedQuantity: number;
+    dimensions?: Record<string, JsonPrimitive>;
+    amount: string;
+    discountedAmount?: string;
+}
+/** Preserve frozen row order when distributing the eight-decimal remainder. */
+declare function allocateDiscountedPriceLines(lines: readonly PriceEvaluationLine[], saleAmount: string): PriceEvaluationLine[];
+interface PriceEvaluationIssue {
+    code: "dimension_mismatch" | "ambiguous_rate" | "missing_usage";
+    metric: BillingMetric;
+    componentIndex: number;
+}
+interface PriceEvaluation {
+    status: "rated" | "incomplete";
+    amount: string;
+    lines: PriceEvaluationLine[];
+    issues: PriceEvaluationIssue[];
+}
+declare function validateNormalizedUsage(value: unknown): asserts value is NormalizedUsageV1;
+/**
+ * Deterministically rates normalized usage without mutating wallets or billing
+ * records. Amounts are rounded half-up to the database's eight-decimal money
+ * scale per line; ceil rates round usage units before multiplying the price.
+ */
+declare function evaluatePriceRule(ruleValue: unknown, usageValue: unknown): PriceEvaluation;
+declare function validatePriceRule(value: unknown): asserts value is PriceRule;
+
+type MeteringKind = "token" | "non_token" | "mixed";
+type UsageEvidenceStatus = "complete" | "partial" | "missing" | "invalid" | "not_expected";
+interface MeteringContract {
+    schemaVersion: 1;
+    kind: MeteringKind;
+    metrics: ReadonlyArray<{
+        metric: BillingMetric;
+        requirement: "required" | "conditional" | "informational";
+        whenFeature?: string;
+    }>;
+}
+interface UsageEvidenceAssessment {
+    kind: MeteringKind | "unknown";
+    evidenceStatus: UsageEvidenceStatus;
+    expectedMetrics: BillingMetric[];
+    observedMetrics: BillingMetric[];
+    missingMetrics: BillingMetric[];
+    issues: string[];
+}
+declare function validateMeteringContract(value: unknown): asserts value is MeteringContract;
+/** Evidence completeness is independent of sale/cost prices and delivery success. */
+declare function assessUsageEvidence(contract: unknown, usage: unknown, features?: Readonly<Record<string, boolean>>): UsageEvidenceAssessment;
+
+type ModelModality = "language" | "embedding" | "reranker" | "image" | "video" | "audio" | "world" | "multimodal" | "other";
+interface ModelEndpointSummary {
+    key: string;
+    label: string;
+    operation: string;
+    protocol: string;
+    method: string;
+    path: string;
+    capabilities: string[];
+    /** Task execution of this native endpoint, not a second model parameter definition. */
+    sourceEndpointKey?: string | null;
+}
+interface ModelCapabilitySummary {
+    inputModalities: string[];
+    outputModalities: string[];
+    /** User-facing input patterns such as text-to-video or image-to-image. */
+    inputModes: string[];
+    features: string[];
+}
+interface ModelDateVersion {
+    id: string;
+    label: string;
+    date?: string;
+    isLatest?: boolean;
+}
+interface TaskModelSummary {
+    requestSuccessBuckets?: {
+        start: string;
+        end: string;
+        succeeded: number;
+        total: number;
+    }[];
+    id: string;
+    slug: string;
+    displayName: string;
+    summary?: string;
+    modality: ModelModality;
+    operation: string;
+    category: string;
+    capabilities: ModelCapabilitySummary;
+    tags: string[];
+    endpoints: ModelEndpointSummary[];
+    schemaVersion: number;
+    status: "active";
+    thumbnailUrl?: string;
+    featured?: boolean;
+    family?: string;
+    versionLabel?: string;
+    isRecommended?: boolean;
+    dateVersions?: readonly ModelDateVersion[];
+}
+interface TaskModel extends TaskModelSummary {
+    description?: string;
+    regions: string[];
+    metadata?: JsonObject;
+    /** Public list and customer-facing sale prices. Channel costs are never exposed here. */
+    pricing?: {
+        official: Array<{
+            operation: string;
+            currency: string;
+            rule: PriceRule;
+        }>;
+        sale: Array<{
+            operation: string;
+            currency: string;
+            rule: PriceRule;
+        }>;
+    };
+    familyVersions?: readonly {
+        slug: string;
+        displayName: string;
+        versionLabel?: string;
+        isRecommended?: boolean;
+    }[];
+}
+interface ModelSchema {
+    model: string;
+    version: number;
+    dialect: "https://json-schema.org/draft/2020-12/schema" | string;
+    inputSchema: JsonObject;
+    outputSchema: JsonObject;
+    /** Native wire parameters outside the request body. */
+    headersSchema?: JsonObject;
+    pathSchema?: JsonObject;
+    querySchema?: JsonObject;
+    /** Final native response for an upstream API that creates an asynchronous job. */
+    resultSchema?: JsonObject;
+    /** @deprecated Compatibility projection; presentation annotations live on inputSchema fields as x-ui. */
+    uiSchema: JsonObject;
+    /** @deprecated Compatibility projection; defaults live on inputSchema fields. */
+    defaults: JsonObject;
+    examples: JsonValue[];
+}
+interface ModelResourceOption {
+    id: string;
+    label: string;
+    description?: string;
+    previewUrl?: string;
+}
+interface ModelResourceList {
+    resource: string;
+    status: "ready" | "unavailable";
+    data: readonly ModelResourceOption[];
+    message?: string;
+}
+interface ModelSearchParams {
+    /** Browse published catalog definitions even when execution is not ready. */
+    includeUnavailable?: boolean;
+    query?: string;
+    modality?: ModelModality;
+    operation?: string;
+    category?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+type NexraBillingCurrency = "CNY";
+interface NexraModelOperation {
+    operation: string;
+    inputModalities: readonly string[];
+    outputModalities: readonly string[];
+    inputSchema: JsonObject;
+    outputSchema: JsonObject;
+    metering: MeteringContract;
+}
+interface NexraModelSpec {
+    id: string;
+    contractVersion: number;
+    developer: string;
+    displayName: string;
+    summary?: string;
+    kind: ModelModality;
+    family?: string;
+    versionLabel?: string;
+    aliases: readonly string[];
+    capabilities: ModelCapabilitySummary;
+    operations: readonly NexraModelOperation[];
+}
+interface NexraModelSpecFilter {
+    kind?: ModelModality;
+    operation?: string;
+}
+interface NexraSalePrice {
+    modelId: string;
+    operation: string;
+    currency: NexraBillingCurrency;
+    priceRevision: string;
+    effectiveFrom: string;
+    rule: PriceRule;
+}
+interface CreateNexraQuoteRequest {
+    modelId: string;
+    operation: string;
+    input: JsonObject;
+}
+interface NexraQuote {
+    quoteToken: string;
+    modelId: string;
+    contractVersion: number;
+    priceRevision: string;
+    currency: NexraBillingCurrency;
+    amount: string;
+    maximumAmount?: string;
+    accuracy: "exact" | "estimated";
+    expiresAt: string;
+}
+interface NexraSettlement {
+    amount: string;
+    currency: NexraBillingCurrency;
+    priceRevision: string;
+    billingStatus: "pending" | "succeeded" | "failed" | "refunded" | "unavailable";
+}
+
+interface NexraClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: FetchLike;
+    headers?: HeadersInit;
+    maxRetries?: number;
+}
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface RequestOptions {
+    retryable?: boolean;
+}
+declare class HttpTransport {
+    readonly baseUrl: string;
+    private readonly apiKey?;
+    private readonly fetchImplementation;
+    private readonly defaultHeaders;
+    private readonly maxRetries;
+    constructor(options: NexraClientOptions);
+    url(path: string): string;
+    json<T>(path: string, init?: RequestInit, options?: RequestOptions): Promise<T>;
+    response(path: string, init?: RequestInit, options?: RequestOptions): Promise<Response>;
+}
+declare function jsonBody(value: unknown): Pick<RequestInit, "body" | "headers">;
+declare function queryString(values: Record<string, string | number | undefined>): string;
+declare function sleep(milliseconds: number, signal?: AbortSignal | null): Promise<void>;
+
+declare class CatalogClient {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    quote(request: CreateNexraQuoteRequest, signal?: AbortSignal): Promise<NexraQuote>;
+}
+declare function getModelSpec(modelId: string): NexraModelSpec | undefined;
+declare function listModelSpecs(filter?: NexraModelSpecFilter): readonly NexraModelSpec[];
+
+export { type NormalizedUsageV1 as A, type BillingMetric as B, type CursorPage as C, type PriceEvaluationIssue as D, type PriceEvaluationLine as E, type FetchLike as F, type PriceRule as G, HttpTransport as H, type UsageEvidenceAssessment as I, type JsonObject as J, type UsageEvidenceStatus as K, allocateDiscountedPriceLines as L, type ModelSearchParams as M, type NexraSettlement as N, assessUsageEvidence as O, type PriceEvaluation as P, evaluatePriceRule as Q, getModelSpec as R, jsonBody as S, type TaskModelSummary as T, type UsageComponentEvidence as U, listModelSpecs as V, queryString as W, sleep as X, validateMeteringContract as Y, validateNormalizedUsage as Z, validatePriceRule as _, type JsonValue as a, type TaskModel as b, type ModelSchema as c, CatalogClient as d, type NexraClientOptions as e, BILLING_EXPORT_DIMENSIONS as f, BILLING_METRICS as g, type CreateNexraQuoteRequest as h, type JsonPrimitive as i, type MeteredPriceRate as j, type MeteredPriceRuleV1 as k, type MeteredUsageComponent as l, type MeteringContract as m, type MeteringKind as n, type ModelCapabilitySummary as o, type ModelDateVersion as p, type ModelEndpointSummary as q, type ModelModality as r, type ModelResourceList as s, type ModelResourceOption as t, type NexraBillingCurrency as u, type NexraModelOperation as v, type NexraModelSpec as w, type NexraModelSpecFilter as x, type NexraQuote as y, type NexraSalePrice as z };

package/dist/catalog.d.ts

@@ -0,0 +1 @@
+export { d as CatalogClient, h as CreateNexraQuoteRequest, u as NexraBillingCurrency, v as NexraModelOperation, w as NexraModelSpec, x as NexraModelSpecFilter, y as NexraQuote, z as NexraSalePrice, N as NexraSettlement, R as getModelSpec, V as listModelSpecs } from './catalog-mytCeh5t.js';

package/dist/catalog.js

@@ -0,0 +1,10 @@
+import {
+  CatalogClient,
+  getModelSpec,
+  listModelSpecs
+} from "./chunk-ADKRTC6X.js";
+export {
+  CatalogClient,
+  getModelSpec,
+  listModelSpecs
+};