@plurnk/plurnk-providers 1.3.12 → 1.4.0

package/dist/telemetry.js

@@ -1,85 +0,0 @@
-// Provider telemetry — the TelemetryEvent envelope for transport failures.
-//
-// TelemetryEvent is plurnk's cross-ecosystem error envelope (canonical schema:
-// @plurnk/plurnk-grammar's schemas.plurnk.dev/v0/TelemetryEvent.json). It is
-// mirrored here STRUCTURALLY rather than imported, so the framework keeps zero
-// dependency on grammar (see SPEC §11). Consumers route provider events through
-// the same `source` + `kind` discriminator as parse/rail events.
-import { APICallError, RetryError } from "ai";
-// Build a provider source label (`provider:<vendor>`), schema-pattern-valid.
-export const providerSource = (vendor) => `provider:${vendor}`;
-// A transport failure carrying its TelemetryEvent classification. IS-an Error
-// (existing catchers keep working); telemetry-aware consumers call
-// toTelemetryEvent() and route on source+kind.
-export class ProviderError extends Error {
-    source;
-    kind;
-    status;
-    constructor(source, kind, message, options = {}) {
-        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = "ProviderError";
-        this.source = source;
-        this.kind = kind;
-        this.status = options.status ?? null;
-    }
-    toTelemetryEvent() {
-        return { source: this.source, kind: this.kind, message: this.message, position: null };
-    }
-}
-// An OpenAI-shaped error body carries error.type. null when the body is absent,
-// non-JSON (a proxy/CDN HTML page), or unshaped — none of which is a match.
-const wireErrorType = (body) => {
-    try {
-        const { error } = JSON.parse(body);
-        return typeof error?.type === "string" ? error.type : null;
-    }
-    catch {
-        return null;
-    }
-};
-// Map a thrown transport error to a (kind, message). Conservative; the message
-// is factual, no guidance prose (consumer SPEC §15.1 policy).
-export const classifyProviderError = (err) => {
-    if (RetryError.isInstance(err))
-        return classifyProviderError(err.lastError);
-    if (APICallError.isInstance(err)) {
-        const status = err.statusCode ?? 0;
-        const message = err.message;
-        const body = err.responseBody ?? "";
-        if (status === 401 || status === 403)
-            return { kind: "unauthorized", message };
-        if (status === 402)
-            return { kind: "quota_exceeded", message };
-        if (status === 429)
-            return { kind: "rate_limit", message };
-        if (status >= 500)
-            return { kind: "network_failure", message };
-        // A flagged 422 identifies a grammar-rejected exchange. It is not
-        // transport replay policy; the engine decides whether to sample again.
-        if (status === 422 && wireErrorType(body) === "grammar_invalid")
-            return { kind: "grammar_invalid", message };
-        return { kind: "invalid_response", message };
-    }
-    const wire = err;
-    if (wire?.type === "grammar_invalid") {
-        return {
-            kind: "grammar_invalid",
-            message: typeof wire.message === "string" ? wire.message : "grammar-invalid response",
-        };
-    }
-    const e = err;
-    const message = (e?.message ?? String(err)) || "request failed";
-    // Timeouts / fetch-level failures are transport, not a usable response.
-    return { kind: "network_failure", message };
-};
-// Wrap any thrown error as a ProviderError tagged with this provider's source.
-// Already-classified errors pass through unchanged.
-export const toProviderError = (err, source) => {
-    if (err instanceof ProviderError)
-        return err;
-    const underlying = RetryError.isInstance(err) ? err.lastError : err;
-    const { kind, message } = classifyProviderError(underlying);
-    const status = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
-    return new ProviderError(source, kind, message, { status, cause: err });
-};
-//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/src/telemetry.test.ts

@@ -1,69 +0,0 @@
-import test from "node:test";
-import { strict as assert } from "node:assert";
-import { APICallError } from "ai";
-import { ProviderError, classifyProviderError, toProviderError, providerSource } from "./telemetry.ts";
-
-const apiError = (statusCode: number, responseBody = "body") => new APICallError({
-    message: `request failed (${statusCode})`,
-    url: "https://example.test/v1/chat/completions",
-    requestBodyValues: {},
-    statusCode,
-    responseBody,
-});
-
-// Schema pattern for TelemetryEvent.source (from grammar's TelemetryEvent.json).
-const SOURCE_PATTERN = /^[a-z]+(:[a-z][a-z0-9-]*)?$/;
-
-test("providerSource produces a schema-valid colon-namespaced source", () => {
-    assert.equal(providerSource("openai"), "provider:openai");
-    assert.match(providerSource("openrouter"), SOURCE_PATTERN);
-    assert.match(providerSource("xai"), SOURCE_PATTERN); // contains no underscore — fine
-});
-
-test("classifyProviderError maps HTTP status to kind", () => {
-    const k = (status: number) => classifyProviderError(apiError(status)).kind;
-    assert.equal(k(401), "unauthorized");
-    assert.equal(k(403), "unauthorized");
-    assert.equal(k(402), "quota_exceeded");
-    assert.equal(k(429), "rate_limit");
-    assert.equal(k(500), "network_failure");
-    assert.equal(k(503), "network_failure");
-    assert.equal(k(400), "invalid_response");
-    assert.equal(k(404), "invalid_response");
-});
-
-test("classifyProviderError: a 422 flagged grammar_invalid is distinct (#548); other 422s are invalid responses", () => {
-    const rejected = apiError(422, JSON.stringify({ error: { type: "grammar_invalid", message: "non-conforming emission rejected: ..." } }));
-    assert.equal(classifyProviderError(rejected).kind, "grammar_invalid");
-    assert.equal(classifyProviderError(apiError(422, JSON.stringify({ error: { type: "invalid_request_error" } }))).kind, "invalid_response");
-    assert.equal(classifyProviderError(apiError(422, "<html>Bad</html>")).kind, "invalid_response");
-});
-
-test("classifyProviderError treats non-HTTP errors as network_failure", () => {
-    assert.equal(classifyProviderError(new TypeError("fetch failed")).kind, "network_failure");
-    const timeout = Object.assign(new Error("timed out"), { name: "TimeoutError" });
-    assert.equal(classifyProviderError(timeout).kind, "network_failure");
-});
-
-test("ProviderError.toTelemetryEvent emits the canonical envelope", () => {
-    const e = new ProviderError("provider:openai", "rate_limit", "OpenAI 429 - slow down", { status: 429 });
-    const ev = e.toTelemetryEvent();
-    assert.deepEqual(ev, { source: "provider:openai", kind: "rate_limit", message: "OpenAI 429 - slow down", position: null });
-    assert.match(ev.source, SOURCE_PATTERN);
-    assert.ok(e instanceof Error);   // still catchable as a plain Error
-    assert.equal(e.status, 429);
-});
-
-test("toProviderError classifies and tags an HTTP error with the source + status", () => {
-    const cause = apiError(401, "no key");
-    const pe = toProviderError(cause, "provider:groq");
-    assert.equal(pe.kind, "unauthorized");
-    assert.equal(pe.source, "provider:groq");
-    assert.equal(pe.status, 401);
-    assert.equal(pe.cause, cause);
-});
-
-test("toProviderError passes an existing ProviderError through unchanged", () => {
-    const original = new ProviderError("provider:xai", "rate_limit", "429");
-    assert.equal(toProviderError(original, "provider:other"), original);
-});

package/src/telemetry.ts

@@ -1,116 +0,0 @@
-// Provider telemetry — the TelemetryEvent envelope for transport failures.
-//
-// TelemetryEvent is plurnk's cross-ecosystem error envelope (canonical schema:
-// @plurnk/plurnk-grammar's schemas.plurnk.dev/v0/TelemetryEvent.json). It is
-// mirrored here STRUCTURALLY rather than imported, so the framework keeps zero
-// dependency on grammar (see SPEC §11). Consumers route provider events through
-// the same `source` + `kind` discriminator as parse/rail events.
-
-import { APICallError, RetryError } from "ai";
-
-// Required by the schema: source (producer id) + kind (discriminator). message
-// and position are optional. A transport failure isn't localizable, so it carries
-// a null position; a `grammar_unenforced` event (#24) carries the divergence
-// code-point offset into the model's emission, so the consumer can render a
-// snippet around it — same recovery affordance the consumer already gives DSL
-// parse errors.
-export type TelemetryEvent = {
-    source: string;            // e.g. "provider:openai" — schema pattern ^[a-z]+(:[a-z][a-z0-9-]*)?$
-    kind: string;              // open vocabulary; providers mint from ProviderTelemetryKind
-    message?: string | null;
-    position?: number | null;
-};
-
-// The kinds plurnk-service routes provider failures on.
-export type ProviderTelemetryKind =
-    | "rate_limit"
-    | "network_failure"
-    | "model_refused"
-    | "invalid_response"
-    | "unauthorized"
-    | "quota_exceeded"
-    // A 422 whose error.type is "grammar_invalid" (#548): the backend served one
-    // generation and rejected it as non-conforming. This identifies the failure;
-    // whether to start another model exchange belongs to the engine.
-    | "grammar_invalid"
-    // Output did not conform to the GBNF. ALWAYS an observation, never a throw:
-    // a completed exchange returns its bytes with this event on
-    // response.telemetry (message + divergence position), whether the grammar
-    // was transported or withheld (filter mode). Discard/retry/escalate is
-    // consumer policy (#24, SPEC §13).
-    | "grammar_unenforced";
-
-// Build a provider source label (`provider:<vendor>`), schema-pattern-valid.
-export const providerSource = (vendor: string): string => `provider:${vendor}`;
-
-// A transport failure carrying its TelemetryEvent classification. IS-an Error
-// (existing catchers keep working); telemetry-aware consumers call
-// toTelemetryEvent() and route on source+kind.
-export class ProviderError extends Error {
-    readonly source: string;
-    readonly kind: ProviderTelemetryKind;
-    readonly status: number | null;
-
-    constructor(source: string, kind: ProviderTelemetryKind, message: string, options: { status?: number | null; cause?: unknown } = {}) {
-        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = "ProviderError";
-        this.source = source;
-        this.kind = kind;
-        this.status = options.status ?? null;
-    }
-
-    toTelemetryEvent(): TelemetryEvent {
-        return { source: this.source, kind: this.kind, message: this.message, position: null };
-    }
-}
-
-// An OpenAI-shaped error body carries error.type. null when the body is absent,
-// non-JSON (a proxy/CDN HTML page), or unshaped — none of which is a match.
-const wireErrorType = (body: string): string | null => {
-    try {
-        const { error } = JSON.parse(body) as { error?: { type?: unknown } };
-        return typeof error?.type === "string" ? error.type : null;
-    } catch {
-        return null;
-    }
-};
-
-// Map a thrown transport error to a (kind, message). Conservative; the message
-// is factual, no guidance prose (consumer SPEC §15.1 policy).
-export const classifyProviderError = (err: unknown): { kind: ProviderTelemetryKind; message: string } => {
-    if (RetryError.isInstance(err)) return classifyProviderError(err.lastError);
-    if (APICallError.isInstance(err)) {
-        const status = err.statusCode ?? 0;
-        const message = err.message;
-        const body = err.responseBody ?? "";
-        if (status === 401 || status === 403) return { kind: "unauthorized", message };
-        if (status === 402) return { kind: "quota_exceeded", message };
-        if (status === 429) return { kind: "rate_limit", message };
-        if (status >= 500) return { kind: "network_failure", message };
-        // A flagged 422 identifies a grammar-rejected exchange. It is not
-        // transport replay policy; the engine decides whether to sample again.
-        if (status === 422 && wireErrorType(body) === "grammar_invalid") return { kind: "grammar_invalid", message };
-        return { kind: "invalid_response", message };
-    }
-    const wire = err as { message?: unknown; type?: unknown; status?: unknown };
-    if (wire?.type === "grammar_invalid") {
-        return {
-            kind: "grammar_invalid",
-            message: typeof wire.message === "string" ? wire.message : "grammar-invalid response",
-        };
-    }
-    const e = err as { name?: string; message?: string };
-    const message = (e?.message ?? String(err)) || "request failed";
-    // Timeouts / fetch-level failures are transport, not a usable response.
-    return { kind: "network_failure", message };
-};
-
-// Wrap any thrown error as a ProviderError tagged with this provider's source.
-// Already-classified errors pass through unchanged.
-export const toProviderError = (err: unknown, source: string): ProviderError => {
-    if (err instanceof ProviderError) return err;
-    const underlying = RetryError.isInstance(err) ? err.lastError : err;
-    const { kind, message } = classifyProviderError(underlying);
-    const status = APICallError.isInstance(underlying) ? underlying.statusCode ?? null : null;
-    return new ProviderError(source, kind, message, { status, cause: err });
-};