npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@izapai/wizard

v0.2.1

Published

Developer setup wizard for iZap integrations, MCP clients, and scaffolds.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

ivancrnetoivancrneto

Keywords

izapwizardmcpdeveloper-toolsscaffold

Readme

iZap Wizard

@izapai/wizard is a developer-facing setup tool for adding iZap to an existing stack. It is intentionally recipe-driven first: deterministic file generation, small explicit edits, dry-run support, and source-backed scaffolds.

Install & run

Run it without installing:

npx @izapai/wizard                              # interactive wizard (on a TTY)
npx @izapai/wizard run "add iZap MCP"           # same, with a stated goal
npx @izapai/wizard plan "connect an AI client"
npx @izapai/wizard mcp add
npx @izapai/wizard --version

Interactive mode

Running izap-wizard with no command on a terminal launches a full-screen, PostHog-style wizard. It first detects your stack and shows a pre-flight confirmation — Directory / Framework / Recipe — with a menu (↑↓ navigate, enter select, q/esc/ctrl-d cancel): Continue, Change framework (override the detected framework — the picker shows display names and marks the detected one), or Cancel. Nothing is written until you choose Continue; --yes skips the prompt.

After you confirm, it runs the real pipeline end-to-end with a live task checklist, tips panel, spinner, progress bar, and Status / Logs / Reference tabs (↹/arrow keys switch tab, q quit) — detect → audit → pick recipe → find edit points → scaffold → write the integration brief → verify.

It degrades gracefully: in a pipe or CI (no TTY), or with --plain, it prints the same steps line-by-line and exits. Without a TTY there is no confirmation menu, so writing requires explicit consent: absent --yes (or --dry-run) the run previews the full plan and exits non-zero instead of writing files. --dry-run previews without writing; --fast skips the animation pacing.

izap-wizard run --plain --dry-run "add iZap MCP"   # preview, rc 0
izap-wizard run --plain "add iZap MCP"             # preview + rc 1: add --yes to apply
izap-wizard run --plain --yes "add iZap MCP"       # applies

Safe writes

Every recipe runs through the same write-safety layer:

  • Never clobbers your edits. If a target file exists with content that differs from what the recipe generates, the run stops with the conflicting paths listed and rc 1. Re-run with --force to overwrite deliberately.
  • .env.example files union-merge. Your existing lines win; only missing keys are appended — so recipes sharing an --output-dir accumulate keys in any order instead of last-writer-wins.
  • .mcp.json merges, never replaces. Foreign servers are preserved, and a malformed .mcp.json aborts the run instead of being silently overwritten.
  • No-ops say so. Re-running an already-applied recipe reports Already up to date — no changes. instead of pretending to apply.
  • Writes stay inside --target-root. An --output-dir that escapes the project root is refused.

Or install the izap-wizard binary globally:

npm install -g @izapai/wizard
izap-wizard doctor

Current commands

Running from source uses node src/bin.mjs; a published install exposes the same surface as izap-wizard.

node src/bin.mjs list                # add --json for machine-readable output
node src/bin.mjs plan
node src/bin.mjs ai "add iZap MCP to my Next.js app"
node src/bin.mjs audit
node src/bin.mjs doctor              # rc 0 on warnings; --strict makes them fatal
node src/bin.mjs mcp add --dry-run
node src/bin.mjs mcp client --stack typescript --dry-run
node src/bin.mjs mcp client --stack python --dry-run
node src/bin.mjs rest client --stack typescript --dry-run
node src/bin.mjs rest client --stack python --dry-run
node src/bin.mjs rest client --stack typescript --auth oauth --dry-run
node src/bin.mjs rest client --stack python --auth oauth --dry-run
node src/bin.mjs webhook receiver --stack typescript --dry-run
node src/bin.mjs webhook receiver --stack python --dry-run
node src/bin.mjs webhook register --stack typescript --dry-run
node src/bin.mjs webhook register --stack python --dry-run
node src/bin.mjs sse client --stack typescript --dry-run
node src/bin.mjs sse client --stack python --dry-run
node src/bin.mjs templates --stack typescript --dry-run
node src/bin.mjs transmissions --stack python --dry-run
node src/bin.mjs send --stack typescript --dry-run
node src/bin.mjs whatsapp connect --dry-run

Platform surfaces

iZap is more than analytics/MCP. The same JWT + business-id header drives three messaging surfaces the wizard can scaffold:

  • templates — manage WhatsApp message templates (GET/POST /api/v1/whatsapp_templates, POST .../sync). TS + Python.
  • transmissions — send WhatsApp broadcasts: preview → confirm → status (/api/v1/transmissions/...). TS + Python.
  • send — send a message or approved template into a live chat (POST /api/v1/chats/{chat_id}/messages and .../messages/template). TS + Python.
  • webhook receiver — verify inbound deliveries with izap-webhook-signature (v1= HMAC-SHA256 of {timestamp}.{raw_body}), reject stale timestamps, and dedupe on izap-webhook-id. TS + Python.
  • webhook register — POST /api/v1/webhook-endpoints/{business_id} and write the one-time signing_secret to .env as IZAP_WEBHOOK_SECRET. TS + Python.
  • whatsapp connect — generate a WhatsApp Business onboarding page wired into the detected framework (Next.js app/pages route, else a static page). It runs Meta Embedded Signup and forwards the code to POST /api/v1/businesses/{id}/whatsapp_cloud/register through a server-side proxy so IZAP_JWT never reaches the browser.
izap-wizard whatsapp connect        # scaffolds app/whatsapp/page.tsx (+ server route) on Next.js

You can also target another directory:

node src/bin.mjs mcp add --target-root /path/to/project
node src/bin.mjs mcp client --stack typescript --output-dir integrations/izap

AI-assisted mode (agent handoff)

izap-wizard ai "<goal>" does not call an LLM and needs no API key. It runs the same deterministic detection + planner, adds framework-specific edit points (where iZap meets your existing code), and writes an izap-integration-brief.md you hand to a coding agent (Claude Code, Cursor, or an MCP-connected agent) — or follow yourself:

$ izap-wizard ai "add iZap MCP to my Next.js app"

Wrote izap-integration-brief.md
  ├─ detected: next, app router
  ├─ recipe: mcp-add
  ├─ edit points:
  │    app/api/izap/route.ts  (add a Route Handler that calls the iZap client)
  │    .env.local             (add the iZap env keys — names only)
  └─ paste into Claude Code / Cursor to apply

--dry-run prints the brief instead of writing it; --json emits the machine-readable plan for programmatic/MCP consumption.

Detected frameworks (for edit points): Next.js (app/pages router), NestJS, Remix, SvelteKit, Nuxt, Astro, Express/Fastify, Vite, FastAPI, Django, Flask, Rails, Laravel, and Gin. The brief also embeds a language-appropriate "call iZap server-side" snippet. Anything else falls back to a generic edit point.

Implemented in 0.2.1

  • Webhook receivers implement the published signing contract: izap-webhook-signature: v1=<hex> over {timestamp}.{raw_body}, 300s replay window, idempotency on izap-webhook-id
  • webhook register scaffolds a TS/Python client for POST /api/v1/webhook-endpoints/{business_id}

Implemented in 0.2.0

Field-QA driven fixes on top of 0.1.0:

  • Overwrite protection: recipes refuse to clobber edited files (--force to override)
  • .env.example union-merge across recipes sharing an --output-dir
  • Malformed .mcp.json aborts instead of being replaced; no-op runs report "already up to date"
  • Goal→recipe ranking: word-boundary matching, notification/reminder vocabulary, and goal-matched recipes always outrank unmatched stack priors
  • Quickstart calls GET /api/v1/auth/users/me (returns your profile with your businesses; the old GET /api/v1/businesses example was a POST-only route and 405'd)
  • TypeScript scaffolds ship a strict tsconfig.json, @types/node, typed code, and a typecheck script — tsc --noEmit passes out of the box
  • Python/TS clients set request timeouts and surface API error bodies; errors print as one-liners, not stack traces
  • Transmissions demos stop at the preview unless run with --confirm
  • Webhook receivers validate IZAP_WEBHOOK_SECRET at boot (no silent request black-hole) and reply with real JSON
  • Non-TTY run without --yes previews and exits non-zero instead of writing
  • TUI input hardening: chunked/CRLF keys, esc/ctrl-d cancel, stdin EOF exits cleanly; framework picker shows display names and marks the detected framework
  • Monorepo detection: both stacks report their frameworks (backend primary), Django detects via requirements.txt/manage.py, and unverified edit points are marked "create this file"
  • whatsapp connect on non-Next stacks: framework-appropriate env naming plus a concrete backend proxy snippet (Django/FastAPI/Flask/Express)
  • Flag validation (--stack/--env/--auth), friendly --target-root errors, doctor --strict, list --json, and a repository field on the npm package

Implemented in 0.1.0

  • Project detection for mixed Node/Python repos
  • Read-only planning mode with recipe recommendations
  • Read-only audit and doctor commands for setup inspection
  • .mcp.json installation/merge for the iZap MCP server
  • TypeScript MCP client scaffold
  • Python MCP client scaffold
  • TypeScript REST client scaffold (JWT bootstrap)
  • Python REST client scaffold (JWT bootstrap)
  • TypeScript REST client scaffold (OAuth 2.0 + PKCE)
  • Python REST client scaffold (OAuth 2.0 + PKCE)
  • TypeScript webhook receiver scaffold
  • Python webhook receiver scaffold
  • TypeScript SSE client scaffold
  • Python SSE client scaffold
  • Dry-run previews for every write
  • --version and end-to-end CLI smoke tests
  • Publishable package (bin, files, publishConfig, LICENSE)
  • AI-assisted ai command: agent-handoff integration brief (no LLM/API key)
  • Interactive full-screen wizard (run / bare launch) with plain + dry-run fallback
  • Interactive --speed slow|normal|fast pacing control
  • Framework detection across 14 stacks with per-framework brief snippets
  • CI publish workflow (push a wizard-v<version> tag)
  • Pre-flight confirmation gate (Continue / Change framework / Cancel) before any write
  • WhatsApp templates + transmissions (broadcasts) clients (TS + Python)
  • WhatsApp Business connect page (Meta Embedded Signup → iZap register), framework-aware

Sources of truth

This scaffold is grounded in the public iZap developer docs:

Design constraints

  • Do not read .env values
  • Never write secrets automatically
  • Prefer idempotent writes and explicit merge behavior
  • Show planned file changes before applying when --dry-run is set
  • Keep recipes small, composable, and easy to audit

Near-term roadmap

  • Optional live-LLM ai --live mode for direct file edits
  • More edit-point heuristics per framework

Contributing

Issues and pull requests are welcome at versariai/izap-wizard — see CONTRIBUTING.md. Report security issues privately per SECURITY.md.