@nathapp/nax-ai 0.1.0

package/dist/providers/catalog.js

@@ -0,0 +1,72 @@
+/**
+ * Normalises a raw provider catalog into nax-ai types.
+ *
+ * STAYS pi-ai-BACKED. Hand-rolling the model catalog is explicitly out of
+ * scope: its pricing and model data are maintained upstream, and taking that
+ * maintenance back is the burden the dependency was chosen to avoid. Unlike
+ * `protocols/`, this layer is not a migration surface.
+ *
+ * This is also where the OAuth allowlist meets a real code path: a provider
+ * declaring a prohibited flow fails to resolve here.
+ */
+import { assertOAuthFlowPermitted } from "../auth/oauth-policy.js";
+export function normaliseCatalog(raw, overrides = []) {
+    const overrideFor = new Map(overrides.map((o) => [o.provider, o]));
+    const providers = new Map();
+    // Keep provider and model identifiers in separate map levels. Both are
+    // externally supplied opaque strings, so a delimiter-based composite key
+    // would make otherwise distinct pairs such as ("a", "b/c") and
+    // ("a/b", "c") collide.
+    const models = new Map();
+    const setModel = (provider, model) => {
+        let providerModels = models.get(provider);
+        if (providerModels === undefined) {
+            providerModels = new Map();
+            models.set(provider, providerModels);
+        }
+        providerModels.set(model.id, model);
+    };
+    for (const rawProvider of raw) {
+        // The gate, on the real path. A prohibited flow must stop resolution here,
+        // not merely fail a unit test of the policy module.
+        if (rawProvider.auth.kind === "oauth") {
+            assertOAuthFlowPermitted(rawProvider.auth.flow);
+        }
+        const override = overrideFor.get(rawProvider.id);
+        const headers = override?.headers ?? rawProvider.headers;
+        providers.set(rawProvider.id, {
+            id: rawProvider.id,
+            baseUrl: override?.baseUrl ?? rawProvider.baseUrl,
+            auth: rawProvider.auth,
+            ...(headers !== undefined ? { headers } : {}),
+            defaultProtocol: rawProvider.defaultProtocol,
+        });
+        for (const rawModel of rawProvider.models) {
+            setModel(rawProvider.id, {
+                id: rawModel.id,
+                provider: rawProvider.id,
+                protocol: rawModel.protocol ?? rawProvider.defaultProtocol,
+                pricing: rawModel.pricing,
+                contextWindow: rawModel.contextWindow,
+                supportsTools: rawModel.supportsTools,
+                thinkingLevels: rawModel.thinkingLevels,
+            });
+        }
+    }
+    // Override-supplied models are applied last so they can replace an entry.
+    for (const override of overrides) {
+        for (const model of override.models ?? []) {
+            setModel(override.provider, model);
+        }
+    }
+    return {
+        provider: (id) => providers.get(id),
+        model: (provider, model) => models.get(provider)?.get(model),
+        listModels: (provider) => {
+            if (provider !== undefined)
+                return [...(models.get(provider)?.values() ?? [])];
+            return [...models.values()].flatMap((providerModels) => [...providerModels.values()]);
+        },
+    };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/providers/catalog.js.map

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

package/dist/providers/pi-catalog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * pi-ai's bundled catalog, normalised into nax-ai types.
+ *
+ * pi-ai is the data source, never the runtime shape: no Model<Api> escapes
+ * this file. That is what lets a hand-written backend obtain baseUrl, headers
+ * and model metadata without importing pi-ai.
+ *
+ * The import is dynamic because the bundled catalog is roughly 1,290 models
+ * across 39 providers and costs about 50 ms to load. A consumer that does not
+ * call this pays nothing.
+ */
+import type { RawProvider } from "./catalog.ts";
+export declare function piProviders(ids?: readonly string[]): Promise<RawProvider[]>;
+//# sourceMappingURL=pi-catalog.d.ts.map

package/dist/providers/pi-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-catalog.d.ts","sourceRoot":"","sources":["../../src/providers/pi-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,cAAc,CAAC;AAqB1D,wBAAsB,WAAW,CAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAsEjF"}

package/dist/providers/pi-catalog.js

@@ -0,0 +1,91 @@
+/**
+ * pi-ai's bundled catalog, normalised into nax-ai types.
+ *
+ * pi-ai is the data source, never the runtime shape: no Model<Api> escapes
+ * this file. That is what lets a hand-written backend obtain baseUrl, headers
+ * and model metadata without importing pi-ai.
+ *
+ * The import is dynamic because the bundled catalog is roughly 1,290 models
+ * across 39 providers and costs about 50 ms to load. A consumer that does not
+ * call this pays nothing.
+ */
+/**
+ * Selects one of our two auth variants from pi-ai's, which may declare both.
+ *
+ * api-key wins when both are offered. This is not a tie-break for tidiness:
+ * anthropic offers both, and mapping it to oauth would make the allowlist in
+ * normaliseCatalog throw and render Anthropic unloadable. The prohibition is
+ * on Anthropic subscription OAuth, never on its API.
+ *
+ * `env` is left unset. pi-ai's variable-name table is module-private, and the
+ * two public routes to it either depend on the ambient environment or return
+ * the secret itself, so there is no honest value to put here.
+ */
+function toProviderAuth(id, auth) {
+    if (auth.apiKey !== undefined)
+        return { kind: "api-key" };
+    if (auth.oauth !== undefined)
+        return { kind: "oauth", flow: id };
+    throw new Error(`Provider "${id}" declares neither api-key nor oauth auth.`);
+}
+export async function piProviders(ids) {
+    const { builtinProviders, getBuiltinModels, getBuiltinProviders } = await import("@earendil-works/pi-ai/providers/all");
+    const { getSupportedThinkingLevels } = await import("@earendil-works/pi-ai");
+    const available = new Set(getBuiltinProviders());
+    const wanted = ids ?? [...available];
+    const unknown = wanted.filter((id) => !available.has(id));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown pi-ai provider(s): ${unknown.join(", ")}.`);
+    }
+    const providers = new Map(builtinProviders().map((provider) => [provider.id, provider]));
+    return wanted.map((id) => {
+        const provider = providers.get(id);
+        if (provider === undefined)
+            throw new Error(`Unknown pi-ai provider: ${id}.`);
+        const piModels = getBuiltinModels(id);
+        const models = piModels.map((model) => ({
+            id: model.id,
+            protocol: model.api,
+            pricing: {
+                input: model.cost.input,
+                output: model.cost.output,
+                cacheRead: model.cost.cacheRead,
+                cacheWrite: model.cost.cacheWrite,
+                ...(model.cost.tiers !== undefined
+                    ? {
+                        tiers: model.cost.tiers.map((tier) => ({
+                            inputTokensAbove: tier.inputTokensAbove,
+                            input: tier.input,
+                            output: tier.output,
+                            cacheRead: tier.cacheRead,
+                            cacheWrite: tier.cacheWrite,
+                        })),
+                    }
+                    : {}),
+            },
+            contextWindow: model.contextWindow,
+            // pi-ai's catalog does not carry a per-model tool flag; every model it
+            // serves through these four protocols accepts tool definitions, and a
+            // model that ignores them fails at request time, not at catalog time.
+            supportsTools: true,
+            thinkingLevels: getSupportedThinkingLevels(model),
+        }));
+        // A provider can span protocols, so the default is the one most of its
+        // models use; per-model `protocol` above is what actually selects.
+        const counts = new Map();
+        for (const model of models)
+            counts.set(model.protocol ?? "", (counts.get(model.protocol ?? "") ?? 0) + 1);
+        const defaultProtocol = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "openai-completions";
+        const baseUrl = provider.baseUrl ?? piModels[0]?.baseUrl ?? "";
+        const headers = piModels[0]?.headers;
+        return {
+            id,
+            baseUrl,
+            auth: toProviderAuth(id, provider.auth),
+            ...(headers !== undefined ? { headers } : {}),
+            defaultProtocol,
+            models,
+        };
+    });
+}
+//# sourceMappingURL=pi-catalog.js.map

package/dist/providers/pi-catalog.js.map

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

package/dist/providers/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Provider and model vocabulary.
+ *
+ * These are nax-ai's own types, deliberately not pi-ai's. A future hand-written
+ * protocol backend needs baseUrl, auth and headers, and must be able to obtain
+ * them without importing pi-ai — which is only true if the catalog is
+ * normalised into this shape at the boundary.
+ */
+import type { ThinkingLevel } from "../protocols/types.ts";
+/** Rates per 1M tokens. nax-ai supplies rates; the consumer computes cost. */
+export interface PricingRates {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+}
+/**
+ * A request-wide pricing tier. The highest matching threshold applies to the
+ * whole request.
+ *
+ * Extends the rates rather than `Pricing` so a tier cannot carry its own tiers.
+ */
+export interface PricingTier extends PricingRates {
+    /** Applies when total input usage exceeds this token count. */
+    readonly inputTokensAbove: number;
+}
+export interface Pricing extends PricingRates {
+    /**
+     * Present for the 22 upstream models that price in tiers. A consumer that
+     * ignores this bills the base rates and will under-report a long-context
+     * request; one that honours it is correct. nax-ai still computes no cost.
+     */
+    readonly tiers?: readonly PricingTier[];
+}
+export type ProviderAuth = 
+/**
+ * `env` is descriptive only and is often absent: the upstream catalog does
+ * not expose variable names in a form that can be read without consulting
+ * the ambient environment. Auth resolution never reads this field.
+ */
+{
+    readonly kind: "api-key";
+    readonly env?: string;
+} | {
+    readonly kind: "oauth";
+    readonly flow: string;
+};
+export interface ResolvedProvider {
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly auth: ProviderAuth;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly defaultProtocol: string;
+}
+export interface ResolvedModel {
+    readonly id: string;
+    readonly provider: string;
+    /** May differ from the provider default: one provider can span several. */
+    readonly protocol: string;
+    readonly pricing: Pricing;
+    readonly contextWindow: number;
+    readonly supportsTools: boolean;
+    /** Empty means the model has no thinking support. */
+    readonly thinkingLevels: readonly ThinkingLevel[];
+}
+/**
+ * Declaration-data overrides only.
+ *
+ * Behaviour changes are a wrapping protocol backend, not an override. Keeping
+ * that line sharp stops this growing into a second, weaker extension mechanism
+ * competing with the registry.
+ */
+export interface ProviderOverride {
+    readonly provider: string;
+    readonly baseUrl?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly models?: readonly ResolvedModel[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,OAAQ,SAAQ,YAAY;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,YAAY;AACtB;;;;GAIG;AACH;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1G,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;CACnD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C"}

package/dist/providers/types.js

@@ -0,0 +1,10 @@
+/**
+ * Provider and model vocabulary.
+ *
+ * These are nax-ai's own types, deliberately not pi-ai's. A future hand-written
+ * protocol backend needs baseUrl, auth and headers, and must be able to obtain
+ * them without importing pi-ai — which is only true if the catalog is
+ * normalised into this shape at the boundary.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Public vocabulary for nax-ai.
+ *
+ * These types are deliberately generic. nax-ai knows nothing about stories,
+ * operations, sessions or permissions — a consumer maps these onto its own
+ * domain at its own boundary. Keeping nax concepts out of this file is what
+ * makes the package reusable; see ADR note in README.
+ */
+/** Provider identifier as understood by the underlying client (e.g. "anthropic"). */
+export type ProviderId = string;
+/** A model selector: provider plus the provider's own model id. */
+export interface ModelRef {
+    readonly provider: ProviderId;
+    readonly model: string;
+}
+/** Role of a message in a conversation. */
+export type MessageRole = "system" | "user" | "assistant";
+export interface Message {
+    readonly role: MessageRole;
+    readonly content: string;
+}
+/**
+ * Token accounting for a single call.
+ *
+ * Cache fields are separate rather than folded into `input` because providers
+ * price cache reads and cache writes differently, and a consumer computing
+ * cost needs them apart. Absent means the provider did not report it — which
+ * is different from zero.
+ */
+export interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+/** Why the provider stopped generating. */
+export type StopReason = "stop" | "length" | "tool_use" | "content_filter" | "error";
+export interface CompleteOptions {
+    readonly model: ModelRef;
+    readonly messages: readonly Message[];
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly signal?: AbortSignal;
+}
+export interface CompleteResult {
+    readonly text: string;
+    readonly usage: TokenUsage;
+    readonly stopReason: StopReason;
+    readonly toolCalls?: readonly import("./protocols/types.ts").ToolCall[];
+    /**
+     * Present only when the provider emitted extended thinking. A caller that
+     * wants to continue this turn (e.g. after running a tool call) must send
+     * these back on the next request's assistant message, in order — without
+     * this field there is no way to construct that follow-up turn.
+     */
+    readonly thinking?: readonly import("./protocols/types.ts").ThinkingBlock[];
+}
+/**
+ * Persistent credential storage, injected by the consumer.
+ *
+ * `modify` is a read-modify-write hook rather than a plain `write` so an
+ * implementation can hold a lock across the whole operation. That matters for
+ * OAuth refresh: concurrent processes sharing one credential file will
+ * otherwise race, and the in-process serialisation the default store provides
+ * does not span processes.
+ */
+export interface CredentialStore {
+    read(providerId: ProviderId): Promise<StoredCredential | undefined>;
+    /**
+     * Returning `undefined` from `fn` removes the credential, and the pi adapter
+     * accordingly maps pi's leave-unchanged `undefined` (its no-op refresh) to
+     * the current credential.
+     */
+    modify(providerId: ProviderId, fn: (current: StoredCredential | undefined) => Promise<StoredCredential | undefined>): Promise<StoredCredential | undefined>;
+    delete(providerId: ProviderId): Promise<void>;
+}
+export type StoredCredential = {
+    readonly kind: "api-key";
+    /**
+     * Opaque. Some stores hold a literal, others a "$VAR" template or a
+     * "!command"; resolving those is the store's business, not nax-ai's.
+     * Never inspect, compare or log this value.
+     */
+    readonly key: string;
+    /** Provider-scoped values, including the substitution scope for `key`. */
+    readonly env?: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "oauth";
+    readonly access: string;
+    readonly refresh: string;
+    /** Epoch milliseconds. */
+    readonly expires: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE1D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,2CAA2C;AAC3C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAErF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,OAAO,sBAAsB,EAAE,QAAQ,EAAE,CAAC;IACxE;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,sBAAsB,EAAE,aAAa,EAAE,CAAC;CAC7E;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IACpE;;;;OAIG;IACH,MAAM,CACJ,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,KAAK,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,GACnF,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IACzC,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,MAAM,gBAAgB,GACxB;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Public vocabulary for nax-ai.
+ *
+ * These types are deliberately generic. nax-ai knows nothing about stories,
+ * operations, sessions or permissions — a consumer maps these onto its own
+ * domain at its own boundary. Keeping nax concepts out of this file is what
+ * makes the package reusable; see ADR note in README.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/usage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Mapping from the underlying client's usage record to this package's.
+ *
+ * Kept as a standalone pure function, separate from any call path, because it
+ * is the piece most likely to be re-pointed at a different backend later: a
+ * hand-rolled protocol would produce the same `TokenUsage` from a different
+ * source shape, and nothing else would need to change.
+ *
+ * Two deliberate differences from the upstream shape:
+ *
+ *  - `reasoning` is dropped. Upstream documents it as a *subset* of `output`,
+ *    so surfacing it alongside would invite double-counting when a consumer
+ *    sums fields to compute cost.
+ *  - `cacheWrite1h` is folded into `cacheWriteTokens` rather than exposed.
+ *    It is a subset of `cacheWrite` that only one provider reports, and the
+ *    generic vocabulary here should not grow a provider-specific field.
+ *
+ * Zeroes are preserved rather than elided: upstream always populates the four
+ * base counters, so a zero means "the provider reported none", which is a
+ * different claim from a missing field.
+ */
+import type { TokenUsage } from "./types.ts";
+/** The subset of the upstream usage record this mapping reads. */
+export interface UpstreamUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+}
+export declare function toTokenUsage(usage: UpstreamUsage): TokenUsage;
+/**
+ * Total billable tokens for a call.
+ *
+ * Cache reads and writes are counted because providers bill them; they are
+ * priced differently from uncached input, which is why the caller needs the
+ * separated `TokenUsage` rather than a single number.
+ */
+export declare function totalTokens(usage: TokenUsage): number;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAO7D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAErD"}

package/dist/usage.js

@@ -0,0 +1,40 @@
+/**
+ * Mapping from the underlying client's usage record to this package's.
+ *
+ * Kept as a standalone pure function, separate from any call path, because it
+ * is the piece most likely to be re-pointed at a different backend later: a
+ * hand-rolled protocol would produce the same `TokenUsage` from a different
+ * source shape, and nothing else would need to change.
+ *
+ * Two deliberate differences from the upstream shape:
+ *
+ *  - `reasoning` is dropped. Upstream documents it as a *subset* of `output`,
+ *    so surfacing it alongside would invite double-counting when a consumer
+ *    sums fields to compute cost.
+ *  - `cacheWrite1h` is folded into `cacheWriteTokens` rather than exposed.
+ *    It is a subset of `cacheWrite` that only one provider reports, and the
+ *    generic vocabulary here should not grow a provider-specific field.
+ *
+ * Zeroes are preserved rather than elided: upstream always populates the four
+ * base counters, so a zero means "the provider reported none", which is a
+ * different claim from a missing field.
+ */
+export function toTokenUsage(usage) {
+    return {
+        inputTokens: usage.input,
+        outputTokens: usage.output,
+        cacheReadTokens: usage.cacheRead,
+        cacheWriteTokens: usage.cacheWrite,
+    };
+}
+/**
+ * Total billable tokens for a call.
+ *
+ * Cache reads and writes are counted because providers bill them; they are
+ * priced differently from uncached input, which is why the caller needs the
+ * separated `TokenUsage` rather than a single number.
+ */
+export function totalTokens(usage) {
+    return usage.inputTokens + usage.outputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,KAAK;QACxB,YAAY,EAAE,KAAK,CAAC,MAAM;QAC1B,eAAe,EAAE,KAAK,CAAC,SAAS;QAChC,gBAAgB,EAAE,KAAK,CAAC,UAAU;KACnC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,YAAY,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC;AAC/G,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nathapp/nax-ai",
+  "version": "0.1.0",
+  "description": "Provider-agnostic LLM client: completions, streaming, tool calls, usage and auth across API-key and OAuth providers.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "release": "bun scripts/release.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "test:live": "vitest --run --config vitest.live.config.ts",
+    "test:watch": "vitest",
+    "check:no-bun-apis": "bun run scripts/check-no-bun-apis.ts",
+    "check:pi-ai-imports": "bun run scripts/check-pi-ai-imports.ts",
+    "lint": "bun x biome check --error-on-warnings src/ test/ scripts/ && bun run check:no-bun-apis && bun run check:pi-ai-imports",
+    "lint:fix": "bun x biome check --write src/ test/ scripts/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.84.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "22.19.19",
+    "typescript": "7.0.2",
+    "vitest": "4.1.9"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "anthropic",
+    "openai",
+    "provider",
+    "streaming"
+  ],
+  "license": "MIT",
+  "author": "William Khoo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nathapp-io/nax-ai.git"
+  },
+  "homepage": "https://github.com/nathapp-io/nax-ai",
+  "bugs": {
+    "url": "https://github.com/nathapp-io/nax-ai/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true,
+    "tag": "next"
+  }
+}