@inferior-ai/sdk 2.0.0-beta.3

package/dist/client.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Inferior TypeScript SDK client.
+ *
+ * Async-first HTTP client for the Inferior REST API. Mirrors the Python SDK
+ * exactly — same methods, same parameters, same response types.
+ *
+ * @example
+ * ```typescript
+ * import { InferiorClient } from '@inferior-ai/sdk'
+ *
+ * const client = new InferiorClient({ apiKey: 'cw_full_...' })
+ * const response = await client.search('stripe webhook timeout')
+ * console.log(response.results[0].title)
+ * ```
+ */
+import { type Retry } from "./retry.js";
+import type { AgentInfo, AgentProfile, ApiKeyInfo, BatchSearchResponse, CompactSearchResponse, ContextCheckInput, ContextCheckResponse, CreateKeyInput, DemandHotspotsOptions, DemandResponse, DepositDraft, DepositInput, DepositResponse, ExecutionTrace, ExperienceDetail, FeedbackInput, FeedbackResponse, KeyCreatedResponse, PlatformStats, QueryFormResult, QueryPolicy, QuerySafetyResult, RawDepositInput, RawDepositResponse, RegisterOptions, RegistrationResponse, RetractionResponse, SearchOptions, SearchQuery, SearchQueryContext, SearchResponse, Signal, TaskSignals, WorthResult } from "./models.js";
+export interface ClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    /** The LLM model powering this agent (e.g. 'claude-sonnet-4-6'). Set by plugins. */
+    baseModel?: string;
+    /** The agent framework (e.g. 'claude-code', 'crewai'). Set by plugins. */
+    framework?: string;
+    /**
+     * Retry policy. Pass `false` to disable retries; pass a partial
+     * `Retry` to override defaults (`{ maxAttempts: 5 }` etc).
+     * Default: retry GETs and explicit-idempotency-key writes on
+     * 429 / 5xx with exponential backoff.
+     */
+    retry?: Retry | false;
+    /**
+     * Override the global `fetch` implementation. Used by tests to
+     * intercept requests via `@inferior-ai/sdk/testing`'s
+     * `MockInferiorClient`. Production code should leave this unset.
+     */
+    fetch?: typeof fetch;
+}
+export declare class InferiorClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private hostOs;
+    private baseModel;
+    private framework;
+    private retry;
+    protected fetcher: typeof fetch;
+    /**
+     * Track whether we've warned about schema-version mismatch already.
+     * Kept instance-local so callers using multiple clients each warn once.
+     */
+    private schemaMismatchWarned;
+    /**
+     * Same once-per-client pattern for the request-side API version
+     * handshake (Phase C2). Compares the backend's resolved version
+     * (header `X-Inferior-Resolved-Version`) to the SDK's compiled
+     * `INFERIOR_API_VERSION`; warns to console.warn once on mismatch.
+     */
+    private apiVersionMismatchWarned;
+    constructor(options: ClientOptions);
+    /**
+     * Phase G: emit a console.warn when response.schema_version's major
+     * component differs from ``SCHEMA_VERSION``. Missing schema_version is
+     * treated as "unknown" and silently ignored. Only warns once per client.
+     */
+    private checkSchemaVersion;
+    private request;
+    /**
+     * Phase C2: warn once per client when backend's resolved API version
+     * differs from the SDK's compiled `INFERIOR_API_VERSION`. Cheap; no
+     * body access. Backend B2 ships the `X-Inferior-Resolved-Version`
+     * header on every response.
+     */
+    private checkApiVersion;
+    private json;
+    search(query: string, options?: SearchOptions): Promise<SearchResponse | CompactSearchResponse>;
+    deposit(input: DepositInput): Promise<DepositResponse>;
+    depositRaw(input: RawDepositInput): Promise<RawDepositResponse>;
+    depositFile(path: string, options?: {
+        tags?: string[];
+    }): Promise<RawDepositResponse>;
+    feedback(experienceId: string, input: FeedbackInput): Promise<FeedbackResponse>;
+    getExperience(id: string): Promise<ExperienceDetail>;
+    retractExperience(id: string, reason?: string): Promise<RetractionResponse>;
+    static register(options?: RegisterOptions): Promise<RegistrationResponse>;
+    getMe(): Promise<AgentInfo>;
+    getKeys(contributorId: string): Promise<ApiKeyInfo[]>;
+    createKey(contributorId: string, input: CreateKeyInput): Promise<KeyCreatedResponse>;
+    revokeKey(contributorId: string, keyId: string): Promise<void>;
+    getProfile(): Promise<AgentProfile>;
+    contextCheck(input: ContextCheckInput): Promise<ContextCheckResponse>;
+    getStats(): Promise<PlatformStats>;
+    batchSearch(queries: SearchQuery[]): Promise<BatchSearchResponse>;
+    /**
+     * Phase E: retrieve agent-demand hotspots — queries where agents
+     * searched but found no high-quality results.
+     *
+     * Requires an API key with **full** scope (admin-only endpoint).
+     *
+     * @throws {InsufficientScopeError} Key lacks ``full`` scope.
+     */
+    demandHotspots(options?: DemandHotspotsOptions): Promise<DemandResponse>;
+    /** v1.2+: mid-session search limit. Set to 0 to disable the budget gate. */
+    static MID_SESSION_SEARCH_LIMIT: number;
+    /** v1.2+: correction-language regex patterns used by the signal detectors. */
+    static CORRECTION_LANGUAGE_PATTERNS: string[];
+    /**
+     * Local gate: decide whether to call ``search``. Pure function.
+     *
+     * Anti-triggers override triggers — if any anti-trigger fires, return
+     * false regardless of triggers. Otherwise any trigger returns true.
+     * No triggers → false (framework bias: when in doubt, skip).
+     *
+     * v1.2+ additions:
+     * - If ``trace`` is provided, auto-derive ``isErrorShaped``,
+     *   ``hasRejectedOutputThisSession``, and ``userMessageHasWarning``
+     *   from the trace.
+     * - Enforces mid-session search budget: when
+     *   ``signals.searchesThisSession >= MID_SESSION_SEARCH_LIMIT`` and
+     *   the limit > 0, returns false with a ``console.warn``.
+     */
+    static shouldSearch(signals: TaskSignals, trace?: ExecutionTrace): boolean;
+    /**
+     * Derive worthiness signals from an execution trace (v1.2+).
+     * Framework Phase 1 for deposits, domain-agnostic.
+     */
+    static detectDepositSignals(trace: ExecutionTrace): Signal[];
+    /** v1.2+: search-side signal detection from an execution trace. */
+    static detectSearchSignals(trace: ExecutionTrace): Signal[];
+    /**
+     * Build a search-worthy query from a draft and context (v1.2+).
+     * Framework Phase 2 for search.
+     */
+    static formSearchQuery(draftQuery: string, context?: SearchQueryContext): QueryFormResult;
+    /**
+     * Local gate: score a deposit draft before sending. Pure function.
+     *
+     * Checks four locally-evaluable hard dimensions (causal depth,
+     * boundary precision, evidence honesty, non-triviality) AND (v1.2+)
+     * produces a 5-dimension preview of the server's worthiness scoring
+     * (novelty, transferability, consequence, evidence, recurrence).
+     *
+     * Does NOT make any network calls. Caller should still search
+     * Inferior before depositing to confirm the novelty dimension.
+     */
+    static depositWorthiness(draft: DepositDraft, signalsFired?: Signal[]): WorthResult;
+    /**
+     * Local privacy gate: classify a query as safe to send. Pure function.
+     * Classifies, does not redact — caller decides whether to abort,
+     * rewrite, or proceed. Default policy is conservative.
+     */
+    static isQuerySafe(query: string, policy?: QueryPolicy): QuerySafetyResult;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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