Skip to main content

Claude Subscription Support

NeuroLink provides flexible access to Anthropic's Claude models through multiple subscription tiers and authentication methods. This guide covers setup, configuration, and best practices for each tier.

Overview​

Claude is available through different subscription tiers, each offering varying levels of access, rate limits, and model availability:

TierAccess MethodRate LimitsBest For
Freeclaude.ai accountLimited messagesExploration, personal use
ProOAuth + claude.ai5x Free tierProfessional use, higher volume
MaxOAuth + claude.aiUnlimitedHeavy production, no rate limit worries
APIAPI KeyPay-per-tokenProduction systems, programmatic access

Subscription Tiers​

The ClaudeSubscriptionTier type (defined in src/lib/types/subscriptionTypes.ts) supports these values:

  • "free" -- Free tier with basic access and limited usage
  • "pro" -- Professional tier with higher limits and priority access
  • "max" -- Maximum tier with highest limits (alias for max_5)
  • "max_5" -- Max 5x usage tier
  • "max_20" -- Max 20x usage tier
  • "api" -- Direct API access tier for developers and enterprises

Free Tier:

  • Basic access to Claude via claude.ai
  • Limited message quota per day
  • Access to Claude 3 Haiku and Claude 3.5 Haiku models only
  • Good for exploring Claude's capabilities

Pro Subscription ($20/month):

  • Higher usage limits than Free tier
  • Priority access during peak times
  • Access to Haiku and Sonnet model families (Claude 3 Haiku, Claude 3.5 Haiku, Claude 3.5 Sonnet, Claude 3.5 Sonnet V2, Claude Sonnet 4)
  • No access to Opus models

Max Subscription ($100/month):

  • Highest usage limits
  • All models available, including Opus
  • Available in Max, Max 5x, and Max 20x usage multiplier variants

API Access (Pay-per-use):

  • Direct programmatic access
  • No monthly subscription required
  • Pay only for tokens used
  • Full model selection (all models)
  • Production-ready SLAs

Quick Start​

# 1. Set your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# 2. Run a prompt with the Anthropic provider
npx @juspay/neurolink generate "Hello, Claude" --provider anthropic

For Claude Pro/Max subscribers who want to use their subscription quota instead of API billing:

# Authenticate via OAuth (opens browser)
npx @juspay/neurolink auth login anthropic --method oauth

# Verify authentication
npx @juspay/neurolink auth status anthropic

Authentication Methods​

NeuroLink supports two authentication methods for Claude access, defined by the AnthropicAuthMethod type:

  • "api_key" -- Traditional API key authentication
  • "oauth" -- OAuth 2.0 authentication for subscription-based access

The standard method using Anthropic API keys. Best for:

  • Production deployments
  • Server-side applications
  • Predictable billing (pay-per-token)
  • Full API control

OAuth Authentication (Claude Pro/Max)​

OAuth authentication allows you to use your existing Claude Pro or Max subscription through NeuroLink. This is ideal for:

  • Personal development using your existing Pro/Max subscription
  • CLI usage without additional API costs
  • Leveraging your subscription's included usage quota

When you authenticate with OAuth, you are redirected to claude.ai to sign in with your Claude account. After authorizing, you receive an authorization code to paste back into the CLI. NeuroLink then securely stores your tokens for future requests.

Setup Guide​

API Key Setup (Standard)​

Step 1: Get Your API Key​

  1. Visit console.anthropic.com
  2. Sign in or create an account
  3. Navigate to API Keys section
  4. Click Create Key
  5. Copy your new API key (starts with sk-ant-)

Step 2: Configure Environment​

Set the API key in your environment:

# Required: Your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

# Optional: Default model
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"

Step 3: Verify Configuration​

# Using the CLI
pnpm run cli -- generate "Hello, Claude" --provider anthropic

# Or use the installed binary
neurolink generate "Hello, Claude" --provider anthropic

Step 4: SDK Usage​

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

const result = await neurolink.generate({
  input: { text: "Explain machine learning in simple terms" },
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  temperature: 0.7,
  maxTokens: 1000,
});

console.log(result.content);

OAuth Setup (Claude Pro/Max)​

OAuth authentication allows you to use your Claude Pro or Max subscription through NeuroLink, leveraging your subscription quota instead of API billing.

OAuth authentication is designed for personal and development use. For production deployments, use API key authentication for better reliability and SLA guarantees.

Step 1: Start OAuth Authentication​

Use the CLI to initiate the OAuth flow:

# Start OAuth authentication (interactive -- choose method)
pnpm run cli -- auth login anthropic

# Start OAuth authentication directly
pnpm run cli -- auth login anthropic --method oauth

# Or create an API key via OAuth (recommended for Pro/Max users)
pnpm run cli -- auth login anthropic --method create-api-key

The CLI supports three authentication methods for Anthropic:

MethodDescription
api-keyTraditional API key authentication (pay-per-use)
oauthDirect OAuth for Claude Pro/Max subscriptions
create-api-keyCreate a real API key via OAuth using your account

Step 2: Authorize in Browser​

  1. Sign in to your Claude account in the browser (claude.ai)
  2. Review the requested permissions
  3. Click Authorize to grant access
  4. Copy the authorization code shown on the page

Step 3: Complete Authentication​

Paste the authorization code back into the CLI when prompted:

Paste the authorization code: <paste-your-code-here>

The CLI will exchange the code for tokens and store them securely.

Step 4: Verify Authentication​

# Check authentication status
pnpm run cli -- auth status

# Check status for a specific provider
pnpm run cli -- auth status anthropic

# Output example:
# Anthropic [Authenticated]
#   Method: oauth
#   Subscription: pro
#   Token Expires: 2026-02-10T12:00:00Z
#   Refresh Token: Available

Token Management​

OAuth tokens are managed automatically by NeuroLink:

# View token information
pnpm run cli -- auth status

# Refresh tokens manually (usually automatic)
pnpm run cli -- auth refresh anthropic

# Revoke authentication
pnpm run cli -- auth logout anthropic

Token Storage Location:

Credentials are stored at ~/.neurolink/tokens.json with 0o600 file permissions (via the TokenStore class). Legacy CLI-saved credentials may also exist at ~/.neurolink/anthropic-credentials.json. The file format is:

{
  "type": "oauth",
  "oauth": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresAt": 1740000000000,
    "tokenType": "Bearer",
    "scope": "user:profile user:inference"
  },
  "provider": "anthropic",
  "subscriptionTier": "pro",
  "createdAt": 1739000000000,
  "updatedAt": 1739000000000
}

Note: expiresAt is stored as Unix milliseconds (Date.now() scale), not seconds.

The TokenStore class (at src/lib/auth/tokenStore.ts) provides multi-provider token storage with XOR-based obfuscation at ~/.neurolink/tokens.json.

SDK OAuth Usage​

To use OAuth authentication in the SDK, pass authMethod: "oauth" and an oauthToken object to the Anthropic provider constructor via the NeuroLink configuration:

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  authMethod: "oauth",
  oauthToken: {
    accessToken: "your-access-token",
    refreshToken: "your-refresh-token",
    expiresAt: Date.now() + 3600000, // milliseconds (Date.now() scale)
  },
});

const result = await neurolink.generate({
  prompt: "Hello, Claude!",
});

Alternatively, the provider auto-detects OAuth credentials from:

  1. Stored credentials file (~/.neurolink/tokens.json or legacy ~/.neurolink/anthropic-credentials.json) -- highest priority
  2. Environment variables ANTHROPIC_OAUTH_TOKEN or CLAUDE_OAUTH_TOKEN

If either source provides a valid OAuth token, the provider automatically switches to OAuth mode without any explicit authMethod configuration.

AnthropicProvider Direct Usage​

For advanced use cases, you can instantiate AnthropicProvider directly with AnthropicProviderConfig:

import AnthropicProvider from "./lib/providers/anthropic.js";

const provider = new AnthropicProvider(
  "claude-sonnet-4-20250514", // model name
  undefined, // SDK instance (optional)
  {
    authMethod: "oauth",
    oauthToken: {
      accessToken: "your-token",
      refreshToken: "your-refresh-token",
      expiresAt: Date.now() + 3600000,
    },
    subscriptionTier: "pro",
    enableBetaFeatures: true, // default: true
  },
);

The AnthropicProviderConfig interface accepts:

PropertyTypeDefaultDescription
authMethod"api_key" | "oauth"Auto-detectedAuthentication method
subscriptionTierClaudeSubscriptionTierAuto-detectedSubscription tier for model access validation
enableBetaFeaturesbooleantrueInclude beta headers for experimental features
oauthTokenOAuthTokenAuto-detectedOAuth token for OAuth authentication
apiKeystringFrom envAPI key for API key authentication

Auto-Refresh Behavior​

The Anthropic provider automatically refreshes expired OAuth tokens before every generate() and stream() call via the refreshAuthIfNeeded() method. This happens transparently and requires no user intervention.

How auto-refresh works:

  1. Before each API call, the provider checks the expiresAt timestamp on the OAuth token
  2. If the token is expired or within 5 minutes of expiring, a refresh is attempted
  3. The refresh request is sent to https://console.anthropic.com/v1/oauth/token using the stored refresh token
  4. The refreshed token is stored both in-memory (mutated in-place on the same object reference so the fetch wrapper picks it up) and persisted to ~/.neurolink/anthropic-credentials.json
  5. If no refresh token is available and the token is expired, an AuthenticationError is thrown

The createOAuthFetch() function accepts a getter function () => string that is called on each request to retrieve the current access token. Since refreshAuthIfNeeded() mutates oauthToken.accessToken in-place (rather than replacing the object), the getter — () => tokenRef.accessToken — returns the refreshed value automatically on subsequent requests without needing to re-create the fetch wrapper.

Manual refresh via CLI:

pnpm run cli -- auth refresh anthropic

Configuration​

Environment Variables​

VariableDescriptionDefaultRequired
ANTHROPIC_API_KEYAPI key for authentication--Yes*
ANTHROPIC_MODELDefault model to useclaude-3-5-sonnet-20241022No
ANTHROPIC_OAUTH_TOKENOAuth token (JSON or plain string)--No
CLAUDE_OAUTH_TOKENOAuth token (fallback env var)--No
ANTHROPIC_SUBSCRIPTION_TIERExplicit subscription tierAuto-detectedNo

*Required for API key authentication. Not required when using OAuth.

Subscription Tier Detection​

The provider detects the subscription tier in this priority order:

  1. Explicit subscriptionTier passed in AnthropicProviderConfig
  2. ANTHROPIC_SUBSCRIPTION_TIER environment variable (valid values: free, pro, max, max_5, max_20, api)
  3. Inferred from OAuth token scopes (if present)
  4. Default: "pro" when OAuth token is present, "api" when using API key

CLI Options​

# Specify provider and model
pnpm run cli -- generate "Your prompt" --provider anthropic --model claude-sonnet-4-20250514

# Set temperature and max tokens
pnpm run cli -- generate "Your prompt" --provider anthropic --temperature 0.7 --max-tokens 2000

# Use streaming output
pnpm run cli -- stream "Tell me a story" --provider anthropic

# Specify auth method and subscription tier
pnpm run cli -- generate "Your prompt" \
  --provider anthropic \
  --authMethod oauth \
  --subscriptionTier pro

The CLI also supports anthropic-subscription as a provider alias that indicates subscription tier support.

Beta Features​

Anthropic regularly releases new features in beta. NeuroLink includes beta headers automatically when enableBetaFeatures is true (the default).

Beta Headers​

For API key authentication, the following beta headers are included:

anthropic-beta: claude-code-20250219,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14

These correspond to the AnthropicBetaFeature enum values in src/lib/constants/enums.ts:

Enum ValueHeader Value
CLAUDE_CODEclaude-code-20250219
INTERLEAVED_THINKINGinterleaved-thinking-2025-05-14
FINE_GRAINED_STREAMINGfine-grained-tool-streaming-2025-05-14

For OAuth authentication, the fetch wrapper uses different beta headers:

anthropic-beta: oauth-2025-04-20,interleaved-thinking-2025-05-14

The oauth-2025-04-20 header is required for OAuth-authenticated requests. The claude-code-20250219 header is conditionally included only if the original request headers already contain it.

Model Availability by Tier​

Model Access Matrix​

Model access is defined in MODEL_TIER_ACCESS in src/lib/models/anthropicModels.ts:

ModelFreeProMax/Max_5/Max_20API
claude-3-haiku-20240307 (Claude 3 Haiku)YesYesYesYes
claude-3-5-haiku-20241022 (Claude 3.5 Haiku)YesYesYesYes
claude-3-5-sonnet-20241022 (Claude 3.5 Sonnet)NoYesYesYes
claude-3-5-sonnet-v2-20241022 (Claude 3.5 Sonnet V2)NoYesYesYes
claude-sonnet-4-20250514 (Claude Sonnet 4)NoYesYesYes
claude-3-opus-20240229 (Claude 3 Opus)NoNoYesYes
claude-opus-4-20250514 (Claude Opus 4)NoNoYesYes

Key observations:

  • Free tier only gets Haiku models (Claude 3 Haiku and Claude 3.5 Haiku)
  • Pro tier gets Haiku and Sonnet models, but not Opus
  • Max tiers (max, max_5, max_20) and API have access to all models (wildcard "*")

Default Models by Tier​

Each tier has a recommended default model (from DEFAULT_MODELS_BY_TIER):

TierDefault Model
Freeclaude-3-5-haiku-20241022
Proclaude-sonnet-4-20250514
Maxclaude-opus-4-20250514
Max_5claude-opus-4-20250514
Max_20claude-opus-4-20250514
APIclaude-sonnet-4-20250514

Model Tier Enforcement​

When the provider detects that the requested model is not available for the user's subscription tier, it automatically falls back to the recommended model for that tier and logs a warning:

// If a Pro user requests an Opus model:
// - The provider logs a warning
// - Falls back to claude-sonnet-4-20250514 (the Pro default)

You can validate model access programmatically:

import {
  isModelAvailableForTier,
  getRecommendedModelForTier,
  getModelCapabilities,
  ModelAccessError,
} from "./lib/providers/anthropic.js";

// Check if a model is available
const available = isModelAvailableForTier("claude-opus-4-20250514", "pro");
// Returns: false (Opus requires max or api tier)

// Get recommended model for a tier
const recommended = getRecommendedModelForTier("pro");
// Returns: "claude-sonnet-4-20250514"

// Get model metadata
const capabilities = getModelCapabilities("claude-sonnet-4-20250514");
// Returns: { displayName: "Claude Sonnet 4", contextWindow: 200000, maxOutputTokens: 64000, ... }

Choosing the Right Model​

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

// For quick, cost-effective responses (Free tier compatible)
const quickResult = await neurolink.generate({
  input: { text: "Summarize this text..." },
  provider: "anthropic",
  model: "claude-3-5-haiku-20241022",
});

// For balanced performance (Pro tier and above)
const balancedResult = await neurolink.generate({
  input: { text: "Analyze this code..." },
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
});

// For complex reasoning tasks (Max/API tier only)
const complexResult = await neurolink.generate({
  input: { text: "Solve this complex problem..." },
  provider: "anthropic",
  model: "claude-opus-4-20250514",
});

Usage Tracking​

Rate Limit Tracking​

The Anthropic provider tracks rate limit information from API response headers. After each request, you can query usage info:

const provider = new AnthropicProvider("claude-sonnet-4-20250514");

const result = await provider.generate("Hello");

// Get usage information
const usage = provider.getUsageInfo();
if (usage) {
  console.log("Requests made:", usage.requestCount);
  console.log("Tokens used:", usage.tokensUsed);
  console.log("Message quota %:", usage.messageQuotaPercent);
  console.log("Token quota %:", usage.tokenQuotaPercent);
  console.log("Rate limited:", usage.isRateLimited);
}

// Get last response metadata including rate limits
const metadata = provider.getLastResponseMetadata();
if (metadata?.rateLimit) {
  console.log("Requests remaining:", metadata.rateLimit.requestsRemaining);
  console.log("Tokens remaining:", metadata.rateLimit.tokensRemaining);
}

The ClaudeUsageInfo type tracks:

FieldTypeDescription
messagesUsednumberMessages sent in current period
messagesRemainingnumberMessages remaining (-1 if unknown)
tokensUsednumberTotal tokens consumed
tokensRemainingnumberTokens remaining (-1 if unknown)
inputTokensUsednumberInput/prompt tokens consumed
outputTokensUsednumberOutput/response tokens consumed
requestCountnumberTotal API requests made
isRateLimitedbooleanWhether currently rate limited
rateLimitExpiresAtnumber?When rate limit expires (ms timestamp)
messageQuotaPercentnumberPercentage of message quota used (0-100)
tokenQuotaPercentnumberPercentage of token quota used (0-100)

Rate Limit Handling​

The provider automatically logs warnings when approaching rate limits:

  • When fewer than 5 requests remain in the current window
  • When token usage exceeds 90% of the token limit

Rate limit information is parsed from these Anthropic response headers:

  • anthropic-ratelimit-requests-limit
  • anthropic-ratelimit-requests-remaining
  • anthropic-ratelimit-requests-reset
  • anthropic-ratelimit-tokens-limit
  • anthropic-ratelimit-tokens-remaining
  • anthropic-ratelimit-tokens-reset
  • retry-after

Monitoring API Usage​

For API key authentication, monitor token usage from generate results:

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

const result = await neurolink.generate({
  input: { text: "Your prompt" },
  provider: "anthropic",
});

// Access usage information from the result
console.log("Input tokens:", result.usage?.inputTokens);
console.log("Output tokens:", result.usage?.outputTokens);
console.log("Total tokens:", result.usage?.totalTokens);

OAuth Implementation Details​

OAuth Flow​

NeuroLink's OAuth implementation follows the same approach used by the official Claude Code CLI. The AnthropicOAuth class in src/lib/auth/anthropicOAuth.ts implements:

  1. PKCE Flow (S256): Uses Proof Key for Code Exchange with SHA-256 code challenge method
  2. Authorization Endpoint: https://claude.ai/oauth/authorize
  3. Token Endpoint: https://console.anthropic.com/v1/oauth/token
  4. Redirect URI: https://console.anthropic.com/oauth/code/callback
  5. Default Scopes: org:create_api_key, user:profile, user:inference

OAuth Constants​

Key constants from src/lib/auth/anthropicOAuth.ts:

ConstantValue
CLAUDE_CODE_CLIENT_ID9d1c250a-e61b-44d9-88ed-5944d1962f5e
ANTHROPIC_AUTH_URLhttps://claude.ai/oauth/authorize
ANTHROPIC_TOKEN_URLhttps://console.anthropic.com/v1/oauth/token
ANTHROPIC_REDIRECT_URIhttps://console.anthropic.com/oauth/code/callback
CLAUDE_CLI_USER_AGENTclaude-cli/2.1.2 (external, cli)
MCP_TOOL_PREFIXmcp_

API Request Requirements for OAuth​

When using OAuth tokens, the createOAuthFetch() wrapper automatically applies these transformations:

// Required headers applied by the OAuth fetch wrapper
headers: {
  "Authorization": `Bearer ${accessToken}`,  // NOT x-api-key
  "anthropic-beta": "oauth-2025-04-20,interleaved-thinking-2025-05-14",
  "User-Agent": "claude-cli/2.1.2 (external, cli)"
}

// URL modified for /v1/messages endpoint
url: "https://api.anthropic.com/v1/messages?beta=true"

Additionally, the OAuth fetch wrapper:

  • Prefixes tool names with mcp_ in outgoing requests (both tool definitions and tool_use blocks in messages)
  • Strips the mcp_ prefix from tool names in streaming responses
  • Removes the x-api-key header (OAuth uses Authorization: Bearer instead)

OAuthToken Type​

The OAuthToken type (from src/lib/types/subscriptionTypes.ts) used across the provider:

type OAuthToken = {
  accessToken: string; // Required: access token for API requests
  refreshToken?: string; // Optional: for obtaining new access tokens
  expiresAt?: number; // Optional: Unix milliseconds (Date.now() scale)
  tokenType?: string; // Optional: typically "Bearer"
  scopes?: string[]; // Optional: granted scopes
};

Note: expiresAt is stored in milliseconds (matching Date.now()), not seconds.

Known Limitations​

OAuth tokens obtained through this flow may have model access restrictions enforced by Anthropic. Some users report that certain models return "This credential is only authorized for use with Claude Code" errors.

Current limitations observed:

Model FamilyOAuth AccessNotes
Claude 3 HaikuWorksReliable access
Claude 3.5 HaikuWorksReliable access
Claude Sonnet 4VariesMay return authorization errors
Claude Opus 4VariesMay return authorization errors

Workarounds:

  1. Use API Key Authentication: For production use, API key authentication is more reliable
  2. Create API Key via OAuth: Use pnpm run cli -- auth login anthropic --method create-api-key to create a real API key through https://api.anthropic.com/api/oauth/claude_cli/create_api_key (requires org:create_api_key scope)
  3. Use Haiku Models: Haiku models appear to have more consistent OAuth access

Troubleshooting​

Common Issues and Solutions​

Authentication Errors​

Issue: "Invalid API key" error

Error: Invalid Anthropic API key. Please check your ANTHROPIC_API_KEY environment variable.

Solution:

  1. Verify your API key starts with sk-ant-
  2. Check for extra spaces or characters
  3. Ensure the key is active in console.anthropic.com
# Verify environment variable is set correctly
echo $ANTHROPIC_API_KEY | head -c 20
# Should output: sk-ant-api03-xxxx...

OAuth Token Expired​

Issue: "OAuth token expired and no refresh token available" error

Solution:

# Refresh the token
pnpm run cli -- auth refresh anthropic

# Or re-authenticate
pnpm run cli -- auth login anthropic

Note: If a refresh token is available, the provider will automatically refresh expired tokens before each generate() or stream() call. Manual refresh is only needed if automatic refresh fails.

Rate Limit Exceeded​

Issue: "Rate limit exceeded" (429) errors

Solution:

  1. For Free tier: Upgrade to Pro or Max for higher limits
  2. For API: Request a rate limit increase from Anthropic
  3. Monitor rate limit headers via provider.getUsageInfo() and provider.getLastResponseMetadata()

Model Access Denied​

Issue: Model falls back to a different model than requested

The provider logs a warning when the requested model is not available for the detected subscription tier and automatically falls back to the recommended model. To fix:

  1. Check your subscription tier supports the model (see Model Access Matrix)
  2. Set the correct tier via ANTHROPIC_SUBSCRIPTION_TIER environment variable
  3. For Opus models, a Max or API tier is required

OAuth Callback Failure​

Issue: OAuth callback never completes

Solution:

  1. Ensure no browser extensions are blocking redirects
  2. The CLI uses the code-based redirect flow (code is shown on the page for you to copy)
  3. Try a different browser
  4. Check the authorization code has not expired (codes are single-use and time-limited)

Debugging Tips​

Enable debug logging for detailed information:

# Enable debug mode
export NEUROLINK_DEBUG=true

# Or for verbose output
export NEUROLINK_LOG_LEVEL=debug

# Run your command
pnpm run cli -- generate "Test prompt" --provider anthropic

The provider logs detailed debug information for:

  • Auth method detection
  • OAuth token refresh attempts
  • Rate limit warnings
  • Model tier fallback decisions

Getting Help​

If issues persist:

  1. Check the NeuroLink troubleshooting guide
  2. Visit Anthropic's documentation
  3. Open an issue on GitHub

Best Practices​

Security​

  • Never commit API keys to version control
  • Use environment variables or secrets management
  • Rotate API keys periodically
  • OAuth credentials are stored with 0o600 permissions in ~/.neurolink/
# Use .env file (not committed to git)
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

# Add to .gitignore
echo ".env" >> .gitignore

Cost Optimization​

  1. Use Haiku for simple tasks: Cheapest model, available on all tiers
  2. Set appropriate maxTokens: Avoid unnecessary generation
  3. Monitor usage: Check provider.getUsageInfo() for quota tracking

Reliability​

  1. Use timeouts: Prevent hanging requests
  2. Consider fallbacks: Configure alternative providers
import { NeuroLink, createAIProviderWithFallback } from "@juspay/neurolink";

// Configure with fallback to another provider
const { primary, fallback } = await createAIProviderWithFallback(
  "anthropic",
  "openai",
);

Exported Types and Utilities​

From src/lib/types/subscriptionTypes.ts​

  • ClaudeSubscriptionTier -- Union type: "free" | "pro" | "max" | "max_5" | "max_20" | "api"
  • AnthropicAuthMethod -- Union type: "api_key" | "oauth"
  • OAuthToken -- OAuth token structure with accessToken, refreshToken?, expiresAt?, tokenType?, scopes?
  • AnthropicRateLimitInfo -- Rate limit data parsed from response headers
  • AnthropicResponseMetadata -- Response metadata including rate limits, request ID, server timing
  • ClaudeUsageInfo -- Usage tracking with messages, tokens, quotas
  • ClaudeQuotaInfo -- Quota limits per tier
  • SubscriptionFeatures -- Per-tier feature capabilities
  • AnthropicBetaFeatures -- Beta feature flag configuration type

From src/lib/models/anthropicModels.ts​

  • AnthropicModel -- Enum of model identifiers
  • MODEL_TIER_ACCESS -- Model access by tier
  • MODEL_METADATA -- Model metadata (context window, capabilities, etc.)
  • isModelAvailableForTier(model, tier) -- Check model availability
  • getAvailableModelsForTier(tier) -- List all models for a tier
  • getDefaultModelForTier(tier) / getRecommendedModelForTier(tier) -- Get default model
  • getModelMetadata(model) / getModelCapabilities(model) -- Get model metadata
  • validateModelAccess(model, tier) -- Throws ModelAccessError if access denied
  • getMinimumTierForModel(model) -- Get minimum tier required
  • ModelAccessError -- Error class for denied model access

From src/lib/constants/enums.ts​

  • ClaudeSubscriptionTier enum (FREE, PRO, MAX, API)
  • AnthropicAuthMethod enum (API_KEY, OAUTH)
  • AnthropicBetaFeature enum (CLAUDE_CODE, INTERLEAVED_THINKING, FINE_GRAINED_STREAMING)
  • TOKEN_EXPIRY_BUFFER_MS -- 5-minute buffer constant (300000ms)

From src/lib/auth/index.ts​

  • AnthropicOAuth -- OAuth 2.0 flow implementation class
  • TokenStore / tokenStore -- Secure token storage
  • OAuthError and subclasses -- OAuth error types
  • createAnthropicOAuth() -- Factory function
  • performOAuthFlow() -- Complete OAuth flow helper
  • startCallbackServer() / stopCallbackServer() -- Local callback server

From src/lib/providers/anthropic.ts​

  • AnthropicProvider -- Provider class with OAuth support
  • AnthropicProviderConfig -- Configuration interface
  • ANTHROPIC_BETA_HEADERS -- Beta headers constant
  • Re-exports: ModelAccessError, isModelAvailableForTier, getRecommendedModelForTier, getModelCapabilities

SDK Programmatic API​

OAuth Flow (Programmatic)​

Use the AnthropicOAuth class to run the OAuth 2.0 + PKCE flow programmatically:

import { AnthropicOAuth, createAnthropicOAuth } from "@juspay/neurolink";

// Create OAuth client with defaults (uses Claude Code's official client ID)
const oauth = createAnthropicOAuth();

// Generate PKCE values
const pkce = await AnthropicOAuth.generatePKCE();
// pkce = { codeVerifier: "...", codeChallenge: "..." }

// Build authorization URL — user visits this in their browser
const authUrl = oauth.generateAuthUrl({
  codeChallenge: pkce.codeChallenge,
  state: pkce.codeVerifier, // state=verifier pattern (OpenCode convention)
});
console.log("Visit:", authUrl);

// After user authorizes, exchange the code for tokens
const tokens = await oauth.exchangeCodeForTokens(code, pkce.codeVerifier);
// tokens = { accessToken, tokenType, expiresAt (Date), refreshToken?, scopes[] }

// Refresh when token expires
const newTokens = await oauth.refreshAccessToken(tokens.refreshToken);

// Validate a token
const validation = await oauth.validateAccessToken(tokens.accessToken);
// validation = { valid: true } or { valid: false, error: "..." }

// Revoke a token
await oauth.revokeToken(tokens.accessToken, "access_token");

Token Store API​

The defaultTokenStore provides secure, file-based token persistence at ~/.neurolink/tokens.json:

import { defaultTokenStore } from "@juspay/neurolink";

// Save tokens for a provider
await defaultTokenStore.saveTokens("anthropic", {
  accessToken: "...",
  refreshToken: "...",
  expiresAt: Date.now() + 3600000, // Unix ms
  tokenType: "Bearer",
});

// Load tokens (returns null if not found)
const tokens = await defaultTokenStore.loadTokens("anthropic");

// Get valid token with auto-refresh (refreshes if expired)
const validToken = await defaultTokenStore.getValidToken("anthropic");

// Check if tokens exist
const hasTokens = await defaultTokenStore.hasTokens("anthropic");

// List providers with stored tokens
const providers = await defaultTokenStore.listProviders();

// Clear tokens for a provider
await defaultTokenStore.clearTokens("anthropic");

// Clear all stored tokens
await defaultTokenStore.clearAllTokens();

// Register auto-refresh callback
defaultTokenStore.setTokenRefresher("anthropic", async (refreshToken) => {
  const oauth = createAnthropicOAuth();
  return await oauth.refreshAccessToken(refreshToken);
});

Model Tier Validation API​

Query model availability and tier access programmatically:

import {
  isModelAvailableForTier,
  getDefaultModelForTier,
  getAvailableModelsForTier,
  getMinimumTierForModel,
  getModelMetadata,
  validateModelAccess,
  compareTiers,
} from "@juspay/neurolink";

// Check model availability for a tier
isModelAvailableForTier("claude-opus-4-20250514", "pro"); // false
isModelAvailableForTier("claude-opus-4-20250514", "max"); // true

// Get recommended model for a tier
getDefaultModelForTier("free"); // "claude-3-5-haiku-20241022"
getDefaultModelForTier("pro"); // "claude-sonnet-4-20250514"
getDefaultModelForTier("max"); // "claude-opus-4-20250514"

// List all models for a tier
getAvailableModelsForTier("pro");
// ["claude-3-haiku-20240307", "claude-3-5-haiku-20241022", "claude-sonnet-4-20250514", ...]

// Find the minimum tier required for a model
getMinimumTierForModel("claude-opus-4-20250514"); // "max"

// Get model metadata (context window, capabilities, etc.)
const meta = getModelMetadata("claude-sonnet-4-20250514");
// { contextWindow: 200000, maxOutputTokens: 64000, supportsVision: true, ... }

// Compare tiers (returns -1, 0, or 1)
compareTiers("pro", "max"); // -1 (pro < max)

// Full validation with error on failure
validateModelAccess("claude-opus-4-20250514", "pro");
// throws ModelAccessError: "Model claude-opus-4-20250514 requires max tier (current: pro)"

Provider Instance API​

Access subscription features on the Anthropic provider instance:

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();
const provider = await neurolink.getProvider("anthropic");

// Check subscription state
provider.getSubscriptionTier(); // "pro" | "max" | "api" | ...
provider.getAuthMethod(); // "oauth" | "api_key"
provider.areBetaFeaturesEnabled(); // true | false

// Validate model access before generation
if (provider.validateModelAccess("claude-opus-4-20250514")) {
  // Model is available for the current tier
}

// Manual token refresh (usually automatic)
await provider.refreshAuthIfNeeded();

// Usage tracking (populated after API calls)
const usage = provider.getUsageInfo();
// { messagesUsed, tokensUsed, inputTokensUsed, outputTokensUsed,
//   lastRequestTokens, tokenQuotaPercent, ... }

// Rate limit info from last response
const metadata = provider.getLastResponseMetadata();
// { rateLimits: { requestsRemaining, tokensRemaining, ... }, requestId }

// Get auth headers (for custom integrations)
const headers = provider.getAuthHeaders();
// { "anthropic-beta": "...", "x-subscription-tier": "pro" }

See Also​