From navan-pack
Sets up local dev environment for Navan API integrations with token caching, request logging, and mock fixtures. Use for new projects or local debugging.
How this skill is triggered — by the user, by Claude, or both
Slash command
/navan-pack:navan-local-dev-loopThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Configure a local development environment for Navan API integrations with token caching, request logging, and mock fixtures. Navan has **no sandbox** — all API calls hit production, making a structured local setup essential.
Configure a local development environment for Navan API integrations with token caching, request logging, and mock fixtures. Navan has no sandbox — all API calls hit production, making a structured local setup essential.
Purpose: Establish a safe local dev workflow that minimizes production API calls during iteration.
navan-install-auth with working OAuth 2.0 credentialstsx for TypeScript execution.env file with NAVAN_CLIENT_ID, NAVAN_CLIENT_SECRET, NAVAN_BASE_URLSet up a clean project layout that separates concerns:
my-navan-integration/
├── .env # Credentials (NEVER commit)
├── .env.example # Template for teammates
├── .gitignore # Must include .env, .token-cache, logs/
├── src/
│ ├── navan-client.ts # API wrapper (from navan-sdk-patterns)
│ ├── navan-types.ts # Response interfaces
│ └── index.ts # Entry point
├── tests/
│ ├── fixtures/ # Recorded API responses for offline dev
│ │ ├── bookings.json
│ │ └── users.json
│ └── navan-client.test.ts
├── logs/ # Request/response logs (gitignored)
├── .token-cache # Cached OAuth token (gitignored)
├── package.json
└── tsconfig.json
Create .env.example as a safe template and enforce .gitignore:
# .env.example — commit this file, NOT .env
NAVAN_CLIENT_ID="your-client-id"
NAVAN_CLIENT_SECRET="your-client-secret"
NAVAN_BASE_URL="https://api.navan.com"
NAVAN_LOG_REQUESTS="true"
NAVAN_USE_FIXTURES="false"
# .gitignore additions for Navan projects
echo ".env" >> .gitignore
echo ".token-cache" >> .gitignore
echo "logs/" >> .gitignore
Persist tokens to disk to avoid hitting /ta-auth/oauth/token on every script run:
// src/token-cache.ts
import { readFileSync, writeFileSync, existsSync } from 'fs';
interface CachedToken {
access_token: string;
expires_at: number; // Unix timestamp in ms
}
const CACHE_FILE = '.token-cache';
export function getCachedToken(): string | null {
if (!existsSync(CACHE_FILE)) return null;
try {
const cached: CachedToken = JSON.parse(readFileSync(CACHE_FILE, 'utf-8'));
if (Date.now() < cached.expires_at - 60_000) {
return cached.access_token;
}
} catch { /* corrupt cache, re-auth */ }
return null;
}
export function setCachedToken(token: string, expiresIn: number): void {
const cached: CachedToken = {
access_token: token,
expires_at: Date.now() + expiresIn * 1000,
};
writeFileSync(CACHE_FILE, JSON.stringify(cached), { mode: 0o600 });
}
Integrate with authentication:
import { getCachedToken, setCachedToken } from './token-cache';
async function getNavanToken(): Promise<string> {
const cached = getCachedToken();
if (cached) return cached;
const response = await fetch(`${process.env.NAVAN_BASE_URL}/ta-auth/oauth/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.NAVAN_CLIENT_ID!,
client_secret: process.env.NAVAN_CLIENT_SECRET!,
}),
});
if (!response.ok) throw new Error(`Auth failed: ${response.status}`);
const data = await response.json();
setCachedToken(data.access_token, data.expires_in);
return data.access_token;
}
Log all API requests and responses for debugging without exposing secrets:
// src/request-logger.ts
import { appendFileSync, mkdirSync, existsSync } from 'fs';
const LOG_DIR = 'logs';
const LOG_FILE = `${LOG_DIR}/navan-api.log`;
export function logRequest(method: string, url: string, status: number, durationMs: number, body?: string): void {
if (process.env.NAVAN_LOG_REQUESTS !== 'true') return;
if (!existsSync(LOG_DIR)) mkdirSync(LOG_DIR, { recursive: true });
const entry = {
timestamp: new Date().toISOString(),
method,
url: url.replace(/client_secret=[^&"]+/g, 'client_secret=***'),
status,
duration_ms: durationMs,
response_preview: body ? body.substring(0, 200) : undefined,
};
appendFileSync(LOG_FILE, JSON.stringify(entry) + '\n');
}
// Usage in API wrapper
const start = Date.now();
const response = await fetch(url, options);
const body = await response.text();
logRequest('GET', url, response.status, Date.now() - start, body);
Record real API responses and replay them during development:
// tests/fixtures/bookings.json
{
"data": [
{
"uuid": "trip-001-abc-def",
"traveler_name": "Jane Smith",
"origin": "SFO",
"destination": "JFK",
"departure_date": "2026-04-01",
"return_date": "2026-04-05",
"booking_status": "confirmed",
"booking_type": "flight"
}
]
}
Use fixtures when NAVAN_USE_FIXTURES is set:
// src/fixture-loader.ts
import { readFileSync } from 'fs';
import { join } from 'path';
const FIXTURE_DIR = join(__dirname, '..', 'tests', 'fixtures');
export function loadFixture<T>(endpoint: string): T | null {
if (process.env.NAVAN_USE_FIXTURES !== 'true') return null;
const filename = endpoint.replace(/^\//, '').replace(/\//g, '_') + '.json';
try {
return JSON.parse(readFileSync(join(FIXTURE_DIR, filename), 'utf-8'));
} catch {
return null;
}
}
// In the API wrapper, check fixtures first
async function request<T>(endpoint: string): Promise<T> {
const fixture = loadFixture<T>(endpoint);
if (fixture) return fixture;
// ... real API call
}
Configure package.json for a fast iteration loop:
{
"scripts": {
"dev": "tsx watch src/index.ts",
"dev:offline": "NAVAN_USE_FIXTURES=true tsx watch src/index.ts",
"test": "vitest",
"test:live": "NAVAN_USE_FIXTURES=false vitest",
"record": "NAVAN_LOG_REQUESTS=true tsx src/record-fixtures.ts",
"logs": "tail -f logs/navan-api.log | python3 -m json.tool"
}
}
Create a one-time script to capture real responses for offline use:
// src/record-fixtures.ts
import { writeFileSync, mkdirSync } from 'fs';
const FIXTURE_DIR = 'tests/fixtures';
mkdirSync(FIXTURE_DIR, { recursive: true });
const token = await getNavanToken();
const endpoints = ['/v1/bookings?page=0&size=50', '/v1/users'];
for (const endpoint of endpoints) {
const response = await fetch(`${process.env.NAVAN_BASE_URL}${endpoint}`, {
headers: { Authorization: `Bearer ${token}` },
});
if (response.ok) {
const data = await response.json();
const filename = endpoint.replace(/^\//, '') + '.json';
writeFileSync(`${FIXTURE_DIR}/${filename}`, JSON.stringify(data, null, 2));
console.log(`Recorded ${endpoint} -> ${filename}`);
} else {
console.error(`Failed to record ${endpoint}: ${response.status}`);
}
}
Successful setup produces:
| Error | Code | Cause | Solution |
|---|---|---|---|
| Unauthorized | 401 | Cached token expired | Delete .token-cache and re-authenticate |
| Forbidden | 403 | Credentials lack required scope | Regenerate credentials with proper permissions |
| Not found | 404 | Fixture file missing for endpoint | Record fixtures with npm run record |
| Rate limited | 429 | Too many dev iterations hitting production | Switch to npm run dev:offline |
| Server error | 500 | Navan service issue | Use fixtures; retry later |
| Maintenance | 503 | Navan downtime | Use NAVAN_USE_FIXTURES=true for offline mode |
Typical dev workflow:
# 1. First time: record fixtures from production
npm run record
# 2. Daily development: use offline mode
npm run dev:offline
# 3. Integration testing: hit production
npm run test:live
# 4. Debug a failure: check logs
npm run logs
With your local dev environment running, see navan-sdk-patterns for production-grade wrapper patterns, or navan-common-errors when you encounter API failures during development.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin navan-packBuilds typed TypeScript NavanAPI client for REST endpoints with OAuth2 token refresh, retries, typed responses, and error handling. For production Navan travel SaaS integrations.
Sets up local dev workflow for Fireflies.ai GraphQL API: project structure, records real responses as fixtures for offline testing, Vitest integration.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.