@superdurable/connectors-sdk 0.1.1 → 0.2.0

package/dist/wire_format-stEVruMs.d.ts

@@ -0,0 +1,190 @@
+import { e as BranchDefinition, F as Failure, q as FailureKind } from './types-D6De3sry.js';
+
+/** Conversation author accepted by portable text generation. */
+type MessageRole = 'user' | 'assistant';
+/** One text-only conversation turn. */
+interface Message {
+    role: MessageRole; /** Nonempty text. */
+    text: string;
+}
+/** One portable JSON object schema, validated before dispatch. */
+interface StructuredOutput {
+    name: string; /** Optional model guidance. */
+    description?: string; /** Portable JSON Schema object. */
+    schema: Record<string, unknown>;
+}
+/** Portable reasoning effort; model rules determine which values are accepted. */
+type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** Provider-neutral generateText input. Zero token limit uses provider default. */
+interface TextGenerationRequest {
+    /** Optional model override; whitespace is trimmed. */ model?: string;
+    /** System or developer instructions. */ instructions?: string;
+    /** Ordered nonempty conversation. */ messages: Message[];
+    /** Optional JSON object output contract. */ structuredOutput?: StructuredOutput;
+    /** Maximum generated tokens, including reasoning tokens where counted. */ maxOutputTokens?: number;
+    /** Sampling temperature; absence preserves the provider default. */ temperature?: number;
+    /** Optional model reasoning effort. */ reasoningEffort?: ReasoningEffort;
+}
+/** Provider-neutral terminal finish classification. */
+type FinishReason = 'stop' | 'length' | 'contentPolicy' | 'refusal';
+/** Token counts reported by the provider; absent counts are zero. */
+interface Usage {
+    /** Prompt tokens. */ inputTokens: number;
+    /** Cached prompt subset. */ cachedInputTokens: number;
+    /** Generated tokens. */ outputTokens: number;
+    /** Reasoning subset. */ reasoningTokens: number;
+    /** Billed total. */ totalTokens: number;
+}
+/** Provider-neutral generateText result; only generated and truncated carry text. */
+interface TextGenerationResponse {
+    /** Non-reasoning text. */ text: string;
+    /** Validated model sent on the request. */ requestedModel: string;
+    /** Provider-reported model, if any. */ servedModel: string;
+    /** Provider response identifier, if any. */ responseId: string;
+    /** Normalized stop reason, if known. */ finishReason: FinishReason | '';
+    /** Safe provider stop token, if known. */ providerFinishReason: string;
+    /** Reported usage. */ usage: Usage;
+}
+/** Stable operation identity shared by LLM providers. */
+declare const TextGenerationOperationID = "generateText";
+/** Required normal completion route. */ declare const GeneratedBranchID = "generated";
+/** Partial output at the token limit. */ declare const TruncatedBranchID = "truncated";
+/** Refusal or content policy stop. */ declare const BlockedBranchID = "blocked";
+/** Conclusive provider rejection. */ declare const ProviderRejectedBranchID = "providerRejected";
+/** Malformed or unusable response. */ declare const InvalidResponseBranchID = "invalidResponse";
+/** Invalid local request or connector definition. */ declare const DefectBranchID = "defect";
+/** Return fresh provider-neutral branches in manifest order. */
+declare function textGenerationBranchDefinitions(): BranchDefinition[];
+/** Return a validation failure shared by all providers, without echoing input. */
+declare function validatePortableRequest(request: TextGenerationRequest): Failure | undefined;
+/** Select request model before the configured model, trimming surrounding whitespace. */
+declare function resolveModel(requestModel: string, connectionModel: string): string;
+/** Model placement determines safe model ID syntax. */
+type ModelIDRule = 'body' | 'pathSegment';
+/** Validate and canonicalize a model ID without including it in errors. */
+declare function validateModelID(rule: ModelIDRule, value: string): string;
+
+/** Optional portable fields the wire format actually sends. */
+interface RequestFeatures {
+    /** Instructions. */ supportsInstructions?: boolean;
+    /** Structured output. */ supportsStructuredOutput?: boolean;
+    /** Token cap. */ supportsMaxOutputTokens?: boolean;
+    /** Temperature. */ supportsTemperature?: boolean;
+    /** Reasoning. */ supportsReasoningEffort?: boolean;
+}
+/** Credential header and safe public prefix. */
+interface CredentialHeader {
+    name: string; /** Public prefix before the secret. */
+    prefix: string;
+}
+/** Model sampling policy; accepted is the zero behavior. */
+type TemperaturePolicy = {
+    kind: 'accepted';
+} | {
+    kind: 'range';
+    minimum: number;
+    maximum: number;
+} | {
+    kind: 'notAccepted';
+};
+/** Accept finite nonnegative temperatures. */ declare function temperatureAccepted(): TemperaturePolicy;
+/** Accept one inclusive temperature range. */ declare function temperatureRange(minimum: number, maximum: number): TemperaturePolicy;
+/** Reject temperature for fixed-sampling models. */ declare function temperatureNotAccepted(): TemperaturePolicy;
+/** How the provider receives structured output. */
+type StructuredOutputMode = 'none' | 'jsonSchema' | 'jsonObjectWithInstruction';
+/** Per-model structured-output transforms; local validation retains original constraints. */
+interface StructuredOutputRules {
+    /** Provider request mode. */ mode: StructuredOutputMode;
+    /** Constraints moved into descriptions. */ keywordsMovedToDescription?: string[];
+    /** Constraints omitted on the wire. */ keywordsRemoved?: string[];
+}
+/** Validate portable schema transform declarations. */
+declare function validateStructuredOutputRules(rules: StructuredOutputRules): void;
+/** Sampling, reasoning, and structured-output rules for one model. */
+interface ModelRequestRules {
+    /** Temperature policy. */ temperature: TemperaturePolicy;
+    /** Accepted effort to wire value. */ reasoningEfforts: Partial<Record<ReasoningEffort, string>>;
+    /** Schema mode and transforms. */ structuredOutput: StructuredOutputRules;
+}
+/** Validated request and selected model rules passed to an encoder. */
+interface EncodeRequestInput {
+    request: TextGenerationRequest; /** Selected model rules. */
+    rules: ModelRequestRules;
+}
+/** One provider HTTP request without its credential. */
+interface EncodedRequest {
+    /** Path including leading slash. */ path: string;
+    /** JSON request bytes. */ body: Uint8Array;
+    /** Extra safe headers. */ headers?: Record<string, string>;
+    /** Whether event-stream is requested. */ isStreaming: boolean;
+}
+/** One decoded text or reasoning segment. */ interface ResponsePart {
+    text: string; /** True for hidden reasoning. */
+    isReasoning?: boolean;
+}
+/** Provider response decoded to the portable shape. */
+interface DecodedResponse {
+    /** Ordered output segments. */ parts: ResponsePart[];
+    /** Model echo. */ servedModel?: string;
+    /** Response identity. */ responseId?: string;
+    /** Provider finish token. */ providerFinishReason?: string;
+    /** Model refusal. */ isRefusal?: boolean;
+    /** Usage. */ usage?: Partial<Usage>;
+}
+/** A complete server-sent event. */ interface ServerSentEvent {
+    data: string; /** Optional event type. */
+    event?: string;
+}
+/** Adapter for one provider's request and response dialect. Functions must be concurrency safe. */
+interface WireFormat {
+    /** Provider identity in failures and receipts. */ providerName: string;
+    /** Model ID validation based on its wire placement. */ modelIDRule: ModelIDRule;
+    /** Optional request fields actually transmitted. */ features: RequestFeatures;
+    /** Sole credential location. */ credentialHeader: CredentialHeader;
+    /** Return per-model rules once after model validation. */ rulesForModel(model: string): ModelRequestRules;
+    /** Encode only a validated request. */ encodeRequest(input: EncodeRequestInput): EncodedRequest;
+    /** Decode a complete 2xx JSON body. */ decodeResponse?: (body: Uint8Array) => DecodedResponse;
+    /** Decode one event and update state. Set hasFinished for a finish token and isDone for a terminal event; throw ProviderReportedError for embedded errors. */
+    decodeStreamEvent?: (event: ServerSentEvent, state: StreamDecodeState, writeTextDelta: (delta: string) => void) => void;
+    /** Accepted provider token to normalized finish reason. */ finishReasons: Record<string, FinishReason>;
+    /** Ordered provider-specific error rules. */ errorRules?: ErrorRule[];
+    /** JSON pointers for safe error tokens. */ errorTokenPointers?: string[];
+    /** Optional provider-specific retry delay reader in milliseconds; thrown or non-finite values defer to Retry-After. */ readErrorRetryDelay?: (body: Uint8Array) => number;
+    /** Response header preference for request ID. */ requestIDHeaders?: string[];
+    /** Whitelisted receipt metadata headers. */ rateLimitHeaders?: string[];
+    /** No-byte timeout in milliseconds; zero disables it. */ stallTimeoutMs?: number;
+}
+/** Mutable state for a single event stream, owned by the pipeline. */
+interface StreamDecodeState {
+    response: DecodedResponse; /** A finish token has arrived. */
+    hasFinished: boolean; /** Terminal DONE event arrived. */
+    isDone: boolean;
+}
+/** One classified provider error rule. */
+interface ErrorRule {
+    statusCode: number; /** Optional exact safe token. */
+    errorToken?: string; /** Chosen outcome. */
+    outcome: ErrorOutcome;
+}
+/** Terminal or retry disposition and failure kind. */
+interface ErrorOutcome {
+    disposition: 'retry' | 'providerRejected' | 'invalidResponse' | 'blocked'; /** Provider-neutral failure category. */
+    kind: FailureKind;
+}
+/** Retry a safely repeatable query. */ declare function retryOutcome(kind: FailureKind): ErrorOutcome;
+/** Select conclusive provider rejection. */ declare function providerRejectedOutcome(kind: FailureKind): ErrorOutcome;
+/** Select exhausted spend or credit. */ declare function quotaExhaustedOutcome(): ErrorOutcome;
+/** Select a content policy block. */ declare function blockedOutcome(): ErrorOutcome;
+/** Select a provider contract violation. */ declare function invalidResponseOutcome(): ErrorOutcome;
+/** Provider error embedded in a 2xx response or stream. Tokens alone may reach a failure. */
+declare class ProviderReportedError extends Error {
+    /** Bounded machine-readable tokens. */ readonly errorTokens: string[];
+    /** Construct without exposing provider message text. */
+    constructor(errorTokens: string[]);
+}
+/** Classify non-2xx or embedded errors using first matching rule and Go defaults. */
+declare function classifyError(rules: readonly ErrorRule[], statusCode: number, tokens: readonly string[], isReported?: boolean): ErrorOutcome;
+/** Reject unsafe or incomplete provider declarations before any call. */
+declare function validateWireFormat(format: WireFormat): void;
+
+export { temperatureNotAccepted as A, BlockedBranchID as B, type CredentialHeader as C, type DecodedResponse as D, type EncodeRequestInput as E, type FinishReason as F, GeneratedBranchID as G, temperatureRange as H, InvalidResponseBranchID as I, textGenerationBranchDefinitions as J, validateModelID as K, validatePortableRequest as L, type Message as M, validateStructuredOutputRules as N, validateWireFormat as O, ProviderRejectedBranchID as P, type ReasoningEffort as R, type ServerSentEvent as S, type TextGenerationRequest as T, type Usage as U, type WireFormat as W, DefectBranchID as a, type EncodedRequest as b, type ErrorOutcome as c, type ErrorRule as d, type MessageRole as e, type ModelIDRule as f, type ModelRequestRules as g, ProviderReportedError as h, type RequestFeatures as i, type ResponsePart as j, type StreamDecodeState as k, type StructuredOutput as l, type StructuredOutputMode as m, type StructuredOutputRules as n, type TemperaturePolicy as o, TextGenerationOperationID as p, type TextGenerationResponse as q, TruncatedBranchID as r, blockedOutcome as s, classifyError as t, invalidResponseOutcome as u, providerRejectedOutcome as v, quotaExhaustedOutcome as w, resolveModel as x, retryOutcome as y, temperatureAccepted as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdurable/connectors-sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Provider-neutral TypeScript contracts for Dex connectors",
   "repository": {
     "type": "git",
@@ -41,6 +41,18 @@
     "./singledispatch": {
       "types": "./dist/singledispatch/index.d.ts",
       "import": "./dist/singledispatch/index.js"
+    },
+    "./textgen": {
+      "types": "./dist/textgen/index.d.ts",
+      "import": "./dist/textgen/index.js"
+    },
+    "./textgen/openaichat": {
+      "types": "./dist/textgen/openaichat/index.d.ts",
+      "import": "./dist/textgen/openaichat/index.js"
+    },
+    "./textgen/textgentest": {
+      "types": "./dist/textgen/textgentest/index.d.ts",
+      "import": "./dist/textgen/textgentest/index.js"
     }
   },
   "files": [
@@ -50,7 +62,7 @@
   ],
   "scripts": {
     "prepack": "npm run build",
-    "build": "tsup src/index.ts src/providerhttp/index.ts src/projectconfig/index.ts src/connectormock/index.ts src/oauthtoken/index.ts src/singledispatch/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/providerhttp/index.ts src/projectconfig/index.ts src/connectormock/index.ts src/oauthtoken/index.ts src/singledispatch/index.ts src/textgen/index.ts src/textgen/openaichat/index.ts src/textgen/textgentest/index.ts --format esm --dts --clean",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src test",
     "test": "vitest run",