@juspay/neurolink 11.1.1 → 11.2.1

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -12,7 +12,7 @@
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import { ProxyTracer } from "../../proxy/proxyTracer.js";
 import { isPermanentRefreshFailure } from "../../proxy/tokenRefresh.js";
-import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, AccountUsageFetchResult, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyLimitsRefreshResponse, ProxyQuotaCooldownUpdate, ProxyPassthroughAccount, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountAdmissionLease, AccountCooldownPlan, AccountQuota, AccountQuotaWindow, AccountUsageFetchResult, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicEntitlementFailure, AnthropicLoopState, AnthropicScopedExhaustion, AnthropicNonOkResult, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeLoggedErrorBuilder, ClaudeRequest, ClaudeProxyRouteRuntimeOptions, ModelRouterInterface, ParsedClaudeError, ProxyAccountRoutingDecision, ProxyAccountSortMetrics, ProxyBodyCaptureLogger, ProxyLimitsRefreshResponse, ProxyQuotaCooldownUpdate, ProxyOveragePolicy, ProxyPassthroughAccount, QueuedAccountAdmission, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
 declare function tryAcquireAccountAdmission(accountKey: string, capacity: number | undefined): AccountAdmissionLease | undefined;
 declare function enqueueAccountAdmission(accountKey: string, capacity: number): QueuedAccountAdmission;
 declare function acquireAccountAdmission(accountKey: string, capacity: number, abortSignal?: AbortSignal, timeoutMs?: number): Promise<AccountAdmissionLease | undefined>;
@@ -54,7 +54,7 @@ declare function resetEpochToMs(resetEpoch: number | undefined, now: number): nu
  * burst / acceleration limit) is transient: honor retry-after as a floor,
  * allow a couple of jittered same-account retries, then a short cooldown.
  */
-declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number, unifiedStatus?: string | undefined): AccountCooldownPlan;
+declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number, unifiedStatus?: string | undefined, policy?: ProxyOveragePolicy): AccountCooldownPlan;
 /**
  * Proactively cool an account when a SUCCESS response reveals a window has just
  * flipped to "rejected" (the boundary request that spends the last of the quota
@@ -62,7 +62,7 @@ declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: nu
  * its reset so the next request skips it instead of discovering the limit via a
  * 429, except when the provider explicitly enables paid overage.
  */
-declare function reconcileCooldownFromQuota(state: RuntimeAccountState, quota: AccountQuota, now: number): ProxyQuotaCooldownUpdate;
+declare function reconcileCooldownFromQuota(state: RuntimeAccountState, quota: AccountQuota, now: number, policy?: ProxyOveragePolicy): ProxyQuotaCooldownUpdate;
 /**
  * Seed each account's runtime quota from the persisted snapshots in
  * ~/.neurolink/account-quotas.json (keyed by label). Runtime state is
@@ -88,6 +88,47 @@ declare function refreshAccountLimits(options?: {
     accountFilter?: string;
     snapshotOnly?: boolean;
 }): Promise<ProxyLimitsRefreshResponse>;
+/**
+ * Publish the operator's extra-usage policy for paths that cannot receive it
+ * explicitly. Callers that make a routing or cooldown decision take it as a
+ * parameter instead — see {@link isOverageUsable} — so a concurrent request or
+ * a hot config reload cannot change the answer mid-flight.
+ *
+ * `undefined` means "no runtime config on this path", which is not a request to
+ * clear an operator's setting, so the current value is kept.
+ */
+declare function setOveragePolicy(policy: ProxyOveragePolicy | undefined): void;
+/**
+ * Find the model-scoped quota window that applies to the requested model.
+ *
+ * Two sources describe the same cap differently: response headers carry the wire
+ * id of the model just served, while the usage API reports a DISPLAY name
+ * ("Fable", "Claude Opus 4.6"). So an exact wire-id match is tried first and
+ * display-name containment over alphanumeric-normalized forms is the fallback.
+ * Among equally specific matches the freshest observation wins, which favours
+ * the continuously-updated header window over a manually-refreshed one.
+ *
+ * Returns null whenever the account reports no applicable, still-fresh scoped
+ * cap — the common case.
+ */
+declare function matchScopedQuotaWindow(quota: AccountQuota | undefined, requestedModel: string | undefined, now?: number): AccountQuotaWindow | null;
+/**
+ * Split a candidate set by whether each account can still serve the requested
+ * model under its model-scoped cap.
+ *
+ * An account is scoped out only on evidence strong enough to act on: a fresh
+ * window, a reset that is actually ticking, a rejected/spent reading, and no
+ * paid extra usage to absorb the overflow. Anything weaker leaves the account
+ * eligible — a stale or mis-parsed window must never be able to empty the pool.
+ *
+ * `exhaustion` is populated only when every candidate is scoped out AND the
+ * evidence is trustworthy, which is what lets the caller report "switch model"
+ * instead of a generic rate limit.
+ */
+declare function evaluateScopedExhaustion(accounts: ProxyPassthroughAccount[], requestedModel: string | undefined, now?: number, policy?: ProxyOveragePolicy): {
+    eligible: ProxyPassthroughAccount[];
+    exhaustion: AnthropicScopedExhaustion | null;
+};
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
  * spend the overall weekly allowance that expires SOONEST first, so quota
@@ -112,7 +153,7 @@ declare function refreshAccountLimits(options?: {
  * Cooling/rejected accounts sort last, soonest-back-to-service first, as
  * last resort.
  */
-declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number): ProxyPassthroughAccount[];
+declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number, requestedModel?: string): ProxyPassthroughAccount[];
 declare function scheduleAdaptiveQuotaRefreshes(accounts: ProxyPassthroughAccount[], orderedAccounts: ProxyPassthroughAccount[], sessionSoftLimit: number, routingMetrics?: ReadonlyMap<string, ProxyAccountSortMetrics>): void;
 declare function scheduleHandoffQuotaRefresh(current: ProxyPassthroughAccount, candidate: ProxyPassthroughAccount | undefined, handoffEpoch: number, sessionSoftLimit: number): void;
 declare function buildRoutingDecision(args: {
@@ -158,6 +199,8 @@ declare function buildClaudeAnthropicFailureResponse(args: {
         body: string;
         contentType?: string;
     } | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
+    scopedExhaustion: AnthropicScopedExhaustion | null;
     sawNetworkError: boolean;
     sawTransientFailure: boolean;
     sawRateLimit: boolean;
@@ -231,6 +274,7 @@ declare function handleAnthropicAuthRetry(args: {
     }) => void;
     lastError: unknown;
     authFailureMessage: string | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
     sawRateLimit: boolean;
     sawTransientFailure: boolean;
     sawNetworkError: boolean;
@@ -270,6 +314,7 @@ declare function handleAnthropicNonOkResponse(args: {
         body: string;
         contentType?: string;
     } | null;
+    entitlementFailure: AnthropicEntitlementFailure | null;
 }): Promise<AnthropicNonOkResult>;
 /**
  * Detect Anthropic's anti-abuse / request-construction 429.
@@ -286,6 +331,7 @@ declare function fetchAnthropicAccountResponse(args: {
     url: string;
     headers: Record<string, string>;
     finalBodyStr: string;
+    requestedModel?: string;
     account: ProxyPassthroughAccount;
     accountState: RuntimeAccountState;
     enabledAccounts: ProxyPassthroughAccount[];
@@ -341,6 +387,29 @@ export declare function isInvalidRequestError(status: number, errBody: string):
  * rather than a terminal client-facing 400.
  */
 export declare function isSubscriptionBetaRejection(status: number, errBody: string): boolean;
+/**
+ * An entitlement rejection: Anthropic refuses THIS credential on organization
+ * or plan policy, e.g. `403 permission_error` /
+ * "OAuth authentication is currently not allowed for this organization."
+ *
+ * The taxonomy makes this safe to rotate on: `permission_error` is reserved for
+ * credential/organization permission, distinct from `invalid_request_error`
+ * (request shape) and `not_found_error`, both already terminal above. No
+ * `permission_error` is caused by the request body, so the identical request
+ * can succeed on a different account.
+ *
+ * Deliberately broad — rotation is cheap and reversible. Persisting the block
+ * is gated on the narrower {@link isDurableEntitlementBlock}.
+ */
+export declare function isAccountEntitlementError(status: number, errBody: string): boolean;
+/**
+ * Whether an entitlement rejection is specific enough to disable the account
+ * until someone re-enables it. Narrower than {@link isAccountEntitlementError}
+ * because disabling is sticky and user-visible: an unrecognised
+ * `permission_error` should rotate through the pool and surface a 403, never
+ * durably remove a credential on a guess.
+ */
+export declare function isDurableEntitlementBlock(status: number, errBody: string): boolean;
 /**
  * Backward-compatible alias — delegates to the shared translation engine.
  */
@@ -374,7 +443,7 @@ export declare const __testHooks: {
     scheduleAdaptiveQuotaRefreshes: typeof scheduleAdaptiveQuotaRefreshes;
     scheduleHandoffQuotaRefresh: typeof scheduleHandoffQuotaRefresh;
     getQuotaRefreshState: (key: string) => import("../../types/proxy.js").ProxyQuotaRefreshRuntimeState;
-    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number) => ProxyAccountRoutingDecision | undefined;
+    buildQuotaRoutingDecision: (accounts: ProxyPassthroughAccount[], now: number, primaryKey: string | undefined, sessionSoftLimit?: number, sessionResetToleranceMs?: number, requestedModel?: string) => ProxyAccountRoutingDecision | undefined;
     buildRoutingDecision: typeof buildRoutingDecision;
     resetEpochToMs: typeof resetEpochToMs;
     seedRuntimeQuotasFromDisk: typeof seedRuntimeQuotasFromDisk;
@@ -413,5 +482,10 @@ export declare const __testHooks: {
     shouldAttemptClaudeFallback: typeof shouldAttemptClaudeFallback;
     executeClaudeFallbackWithRetry: typeof executeClaudeFallbackWithRetry;
     buildClaudeAnthropicFailureResponse: typeof buildClaudeAnthropicFailureResponse;
+    isAccountEntitlementError: typeof isAccountEntitlementError;
+    isDurableEntitlementBlock: typeof isDurableEntitlementBlock;
+    evaluateScopedExhaustion: typeof evaluateScopedExhaustion;
+    matchScopedQuotaWindow: typeof matchScopedQuotaWindow;
+    setOveragePolicy: typeof setOveragePolicy;
 };
 export {};