---
name: juicebox-local-dev-loop-232ca25d0397
description: 'Configure Juicebox local dev workflow.

  Trigger: "juicebox local dev", "juicebox dev setup".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 1.16.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- recruiting
- juicebox
compatibility: Designed for Claude Code
---
# Juicebox Local Dev Loop

## Overview

Local development workflow for Juicebox AI-powered people analysis and recruiting API integration. Provides a fast feedback loop with mock profile search results and candidate enrichment data so you can build talent pipeline tools without consuming live API credits. Toggle between mock mode for rapid iteration and sandbox mode for validating against the real Juicebox API.

## Environment Setup

```bash
cp .env.example .env
# Set your credentials:
# JUICEBOX_API_KEY=jb_live_xxxxxxxxxxxx
# JUICEBOX_BASE_URL=https://api.juicebox.work/v1
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
```

## Dev Server

```typescript
// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/v1", createProxyMiddleware({
    target: process.env.JUICEBOX_BASE_URL,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.JUICEBOX_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3004, () => console.log(`Juicebox dev server on :3004 [mock=${MOCK}]`));
```

## Mock Mode

```typescript
// src/dev/mocks.ts — realistic people search and enrichment responses
export function mountMockRoutes(app: any) {
  app.post("/v1/search", (req: any, res: any) => res.json({
    total: 150,
    profiles: [
      { id: "prof_1", name: "Jane Smith", title: "Senior Engineer", company: "Google", location: "San Francisco, CA", skills: ["TypeScript", "React", "GCP"] },
      { id: "prof_2", name: "Alex Chen", title: "Staff ML Engineer", company: "Meta", location: "New York, NY", skills: ["Python", "PyTorch", "MLOps"] },
    ],
  }));
  app.get("/v1/profiles/:id", (req: any, res: any) => res.json({
    id: req.params.id, name: "Jane Smith", title: "Senior Engineer", company: "Google",
    experience: [{ role: "Senior Engineer", company: "Google", years: 3 }],
    education: [{ school: "MIT", degree: "BS Computer Science" }],
  }));
  app.get("/v1/usage", (_req: any, res: any) => res.json({ creditsUsed: 12, creditsRemaining: 488, plan: "starter" }));
}
```

## Testing Workflow

```bash
npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Integration test against real API
```

## Debug Tips

- Set search `limit` to 5 in development to avoid burning API credits
- Use `/v1/usage` endpoint to monitor credit consumption before switching off mock mode
- Juicebox search queries are natural language — test with specific role titles for better results
- Check `profiles[].skills` array for null values that can break filtering logic
- Log the full request payload to verify boolean filters are serialized correctly

## Error Handling

| Issue | Cause | Fix |
|-------|-------|-----|
| `401 Unauthorized` | Invalid API key | Regenerate at Juicebox dashboard |
| `402 Payment Required` | Credits exhausted | Upgrade plan or wait for monthly reset |
| `400 Bad Request` | Malformed search query | Validate query structure before sending |
| `429 Rate Limited` | Too many requests per minute | Add exponential backoff, use mock mode |
| `ECONNREFUSED :3004` | Dev server not running | Run `npm run dev:mock` first |

## Prerequisites

- A local sandbox configured for mock or synthetic data, secret references instead of literal keys, source/destination allowlists, suppression fixtures, and a tested cleanup command.

## Instructions

1. Start in mock mode and use only synthetic records; do not switch to an integration environment until source authority and owner approval are recorded.
2. Log aggregate diagnostics only, verify suppression and `contacts_exported=0`, and reject requests that contain credentials or contact-level data.
3. Test one canary workflow at a time; halt on scope, policy, quota, or retention drift and restore the known-good configuration.
4. Delete staged data and revoke temporary credentials after collecting the redacted receipt.

## Output

Produce a local-test receipt with environment, mock/integration mode, fixture classification, aggregate result/error counts, suppression/no-export checks, approver, cleanup result, and rollback reference. Exclude requests, identities, and keys.

## Examples

`env=local; mode=mock; fixture=synthetic; requests=5; suppression=pass; contacts_exported=0; cleanup=verified` is a valid development check.

## Resources

- [Juicebox API Docs](https://docs.juicebox.work)

## Next Steps

See `juicebox-debug-bundle`.


---
Source attribution: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/juicebox-pack/skills/juicebox-local-dev-loop/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Jeremy Longshore

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/juicebox-pack/skills/juicebox-local-dev-loop/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: Backend Developer, Frontend Developer, Full-Stack Developer
Specialties: API, Backend, Design, Frontend, Mobile, React, Stripe, Testing
Tools: Juicebox Sdk, Nodemon, Vitest
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: dd5e61a6ea2fa528af0268d88c632def934767c4109e339b3c9a9ff67f18c6ec