@guidify-ai/vapi-studio 0.1.0

package/docs/reference/security.md

@@ -0,0 +1,41 @@
+# Security
+
+## Framework repository
+
+This repo should contain **no secrets**:
+
+- No LLM API keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`) or Vapi tokens in source or committed config
+- No real caller PII in fixtures or tests
+- Use obvious placeholders in docs (e.g. fictional phone numbers in best-practice examples)
+
+## Consuming applications
+
+Your NestJS application should:
+
+- Keep secrets in `.env` — **gitignored**
+- Ship `.env.example` with empty values only
+- Treat runtime logs (`LOG_DIR`) as sensitive in production
+
+## Prompt injection (caller speech)
+
+Caller audio / ASR is **untrusted**. A user asking for a pancake recipe, jailbreak, or “ignore previous instructions” must not change agent behavior or produce spoken off-topic answers.
+
+Vapi Studio’s deterministic model:
+
+- **Brain** returns JSON only (intention scores + allowlisted extract fields) — never caller-facing prose
+- **Supervisor + agent steps** own routing and **all spoken copy**
+- Framework Brain adapters apply [`brainUntrustedInputRules`](../best-practices/brain-and-prompt-injection.md), candidate allowlists, extract sanitization, and a **pre-LLM fail-closed gate** on injection-shaped ASR (all stock JSON-LLM providers share this path)
+
+App authors must not echo raw `userText` or Brain `reason` to the caller, and must not add unconstrained sidecar LLM chat on the same call.
+
+Full guide: **[Brain and prompt injection](../best-practices/brain-and-prompt-injection.md)**.
+
+## Test doubles
+
+Framework and app tests may use values like `sk-mock-not-real` — never real API keys.
+
+## Related
+
+- [Environment variables](./environment-variables.md)
+- [Creating an app](../building-apps/creating-an-app.md)
+- [Brain and prompt injection](../best-practices/brain-and-prompt-injection.md)

package/docs/reference/standard-intentions.md

@@ -0,0 +1,49 @@
+# Standard intentions
+
+Framework-provided intention constants (`STANDARD_INTENTIONS`).
+
+## Portal / global
+
+| Constant | Typical portal node |
+| --- | --- |
+| `studio.isGoodbye` | Goodbye → `endCall` |
+| `studio.isTransferToHuman` | Transfer (re-engage once, then transfer) |
+| `studio.isStillThere` | Still-there (ghosting / silence) |
+| `studio.isMad` | Mad escalation |
+| `studio.isPause` | Pause |
+| `studio.isUnknownTransition` | Unknown recovery (route fallback) |
+| `studio.isContinue` | Resume / continue prior conversation |
+
+## Polarity
+
+| Constant | Use |
+| --- | --- |
+| `studio.isPositive` | Yes / affirm |
+| `studio.isNegative` | No / decline |
+
+## App naming conventions
+
+From [Node conventions](../guides/node-conventions.md):
+
+- **Actions:** `is{VerbPast}…` — `isCollectedFirstName`, `isAcceptedAppointment`
+- **Polarity:** `studio.isPositive` / `studio.isNegative` when appropriate
+- **Framework prefix:** `studio.*` for standard intentions only
+
+## Code intentions
+
+Extend **`CodeIntention`** (register via `VapiStudioModule.forRoot({ intentions })`). Cascade phases (`INTENTION_CASCADE_PHASE`):
+
+| Phase | When |
+| --- | --- |
+| `Force` | Preempt before current node (e.g. need SMS consent) |
+| `Match` | Node eligibility |
+| `Scan` | Brain candidate |
+
+## Application examples
+
+Your app defines intentions in `flow.yaml`, e.g. `isCollectedFirstName`, `isAcceptedAppointment`, `isDidNotReceiveForm`.
+
+## Related
+
+- [Flow schema](./flow-schema.md)
+- [Concepts](../guide/concepts.md)

package/docs/reference/testing.md

@@ -0,0 +1,15 @@
+# Testing
+
+```bash
+yarn install
+yarn build
+yarn test   # tsc + node:test under test/*.test.mjs
+```
+
+Mocked unit tests — no live Vapi or paid Brain in the default suite.
+
+Application integration tests live in **your app repository**, not here.
+
+## Related
+
+- [Installation](../getting-started/installation.md)

package/docs/samples/events/nest-listener.example.ts

@@ -0,0 +1,17 @@
+/**
+ * EXAMPLE — Nest DI listener. Register via:
+ *   VapiStudioModule.forRoot({ eventListeners: [AuditEventListener] })
+ */
+import { Injectable, Logger } from '@nestjs/common';
+import type { StudioEvent, StudioEventListener } from '@guidify-ai/vapi-studio';
+
+@Injectable()
+export class AuditEventListener implements StudioEventListener {
+  private readonly log = new Logger(AuditEventListener.name);
+
+  async handle(event: StudioEvent): Promise<void> {
+    if (event.type === 'ROUTE_DECISION' || event.type === 'ANALYTICS_TAG') {
+      this.log.debug(`${event.type} ${event.conversationId ?? ''}`);
+    }
+  }
+}

package/docs/samples/events/redis-bridge.example.ts

@@ -0,0 +1,44 @@
+/**
+ * EXAMPLE — copy into your Nest app (e.g. src/events/redis-event-bridge.ts).
+ * Not executed by the framework package.
+ *
+ * Bridges onStudioEvent → Redis Streams so a separate consumer (analytics,
+ * warehouse, …) can read the same way Roofr → ecosystem-analytics does.
+ *
+ * Requires: yarn add ioredis
+ * Env: STUDIO_EVENTS_REDIS_URL, STUDIO_EVENTS_REDIS_STREAM (optional)
+ */
+import { onStudioEvent, type StudioEvent } from '@guidify-ai/vapi-studio';
+
+// import Redis from 'ioredis';
+
+export function registerRedisEventBridge(): void {
+  const url = process.env.STUDIO_EVENTS_REDIS_URL?.trim();
+  const stream =
+    process.env.STUDIO_EVENTS_REDIS_STREAM?.trim() || 'studio:events';
+  if (!url) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[events] STUDIO_EVENTS_REDIS_URL unset — Studio events stay in-process only',
+    );
+    return;
+  }
+
+  // const redis = new Redis(url);
+  onStudioEvent(async (event: StudioEvent) => {
+    // await redis.xadd(
+    //   stream,
+    //   '*',
+    //   'id', event.id,
+    //   'type', event.type,
+    //   'ts', event.ts,
+    //   'level', event.level,
+    //   'conversationId', event.conversationId ?? '',
+    //   'runtimeInstanceId', event.runtimeInstanceId ?? '',
+    //   'providerCallId', event.providerCallId ?? '',
+    //   'payload', JSON.stringify(event.payload ?? {}),
+    // );
+    void event;
+    void stream;
+  });
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@guidify-ai/vapi-studio",
+  "version": "0.1.0",
+  "description": "Vapi Studio — deterministic voice agents for Vapi (NestJS)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guidify-ai/vapi-studio.git"
+  },
+  "homepage": "https://github.com/guidify-ai/vapi-studio#readme",
+  "bugs": {
+    "url": "https://github.com/guidify-ai/vapi-studio/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./identity": {
+      "types": "./dist/identity/index.d.ts",
+      "default": "./dist/identity/index.js"
+    },
+    "./docs/best-practices/*": "./docs/best-practices/*",
+    "./agent/AGENTS.md": "./agent/AGENTS.md"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "agent",
+    "scripts",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && yarn build:studio-ui",
+    "build:studio-ui": "yarn --cwd studio-ui install && yarn --cwd studio-ui build",
+    "clean": "rm -rf dist",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "yarn lint && yarn build && node --test test/*.test.mjs",
+    "postinstall": "node -e \"const fs=require('fs');const p=require('path');const s=p.join(__dirname,'scripts','install-agent-refs.cjs');if(fs.existsSync(s)) require('child_process').execFileSync(process.execPath,[s],{stdio:'inherit',env:process.env});\"",
+    "install-agent-refs": "node scripts/install-agent-refs.cjs"
+  },
+  "dependencies": {
+    "uuid": "^11.1.0",
+    "yaml": "^2.7.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/typeorm": "^11.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typeorm": "^0.3.21",
+    "twilio": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "twilio": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@nestjs/common": "^11.0.12",
+    "@nestjs/core": "^11.0.12",
+    "@nestjs/typeorm": "^11.0.0",
+    "@types/node": "^22.13.10",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^10.9.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "ts-morph": "^28.0.0",
+    "typeorm": "^0.3.21",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.69.0"
+  }
+}

package/scripts/fix-access-modifiers.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * One-time / maintenance codemod: explicit public|private|protected on class members;
+ * explicit types on properties when missing (from initializer inference).
+ */
+import { Project, SyntaxKind, Node } from 'ts-morph';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+const project = new Project({
+  tsConfigFilePath: path.join(root, 'tsconfig.json'),
+});
+
+function hasAccessModifier(node) {
+  return (
+    node.hasModifier(SyntaxKind.PublicKeyword) ||
+    node.hasModifier(SyntaxKind.PrivateKeyword) ||
+    node.hasModifier(SyntaxKind.ProtectedKeyword)
+  );
+}
+
+function ensurePublic(node) {
+  if (!hasAccessModifier(node)) {
+    node.toggleModifier('public', true);
+  }
+}
+
+function typeTextFromInitializer(init) {
+  if (!init) return null;
+  if (init.getKind() === SyntaxKind.TrueKeyword || init.getKind() === SyntaxKind.FalseKeyword) {
+    return 'boolean';
+  }
+  if (Node.isNumericLiteral(init)) return 'number';
+  if (Node.isStringLiteral(init)) {
+    const parentInit = init.getParent();
+    if (
+      parentInit &&
+      Node.isAsExpression(parentInit) &&
+      parentInit.getTypeNode()?.getText() === 'const'
+    ) {
+      return init.getLiteralText(); // keep literal for `as const` fields
+    }
+    return 'string';
+  }
+  const t = init.getType();
+  const text = t.getText(init, undefined, undefined);
+  if (!text || text === 'any' || text.includes('import(')) return null;
+  if (text === 'true' || text === 'false') return 'boolean';
+  return text;
+}
+
+for (const sf of project.getSourceFiles('src/**/*.ts')) {
+  let changed = false;
+
+  for (const cls of sf.getClasses()) {
+    for (const member of cls.getMembers()) {
+      if (
+        Node.isPropertyDeclaration(member) ||
+        Node.isMethodDeclaration(member) ||
+        Node.isGetAccessorDeclaration(member) ||
+        Node.isSetAccessorDeclaration(member) ||
+        Node.isConstructorDeclaration(member)
+      ) {
+        ensurePublic(member);
+        changed = true;
+      }
+
+      if (Node.isPropertyDeclaration(member) && !member.getTypeNode()) {
+        const inferred = typeTextFromInitializer(member.getInitializer());
+        if (inferred) {
+          member.setType(inferred);
+          changed = true;
+        }
+      }
+    }
+  }
+
+  if (changed) {
+    sf.saveSync();
+  }
+}
+
+console.log('Access modifiers and property types updated under src/');

package/scripts/install-agent-refs.cjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * Runs on `@guidify-ai/vapi-studio` install. Ensures the consuming app has agent-visible
+ * pointers to docs/best-practices (Cursor rule + stamped AGENTS.md block).
+ *
+ * Yarn/npm set INIT_CWD to the project that invoked install.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const pkgRoot = path.resolve(__dirname, '..');
+const consumerRoot = path.resolve(process.env.INIT_CWD || process.cwd());
+const PKG = '@guidify-ai/vapi-studio';
+
+function isSameDir(a, b) {
+  return path.resolve(a) === path.resolve(b);
+}
+
+/** Skip when installing the framework package itself. */
+if (isSameDir(consumerRoot, pkgRoot)) {
+  process.exit(0);
+}
+
+/** Skip if this does not look like an app that depends on us. */
+const consumerPkgPath = path.join(consumerRoot, 'package.json');
+if (!fs.existsSync(consumerPkgPath)) {
+  process.exit(0);
+}
+
+let consumerPkg;
+try {
+  consumerPkg = JSON.parse(fs.readFileSync(consumerPkgPath, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const deps = {
+  ...(consumerPkg.dependencies || {}),
+  ...(consumerPkg.devDependencies || {}),
+};
+if (!deps[PKG]) {
+  process.exit(0);
+}
+
+const BEGIN = '<!-- VAPI-STUDIO-BEST-PRACTICES:BEGIN -->';
+const END = '<!-- VAPI-STUDIO-BEST-PRACTICES:END -->';
+
+const agentsBlock = `${BEGIN}
+## Vapi Studio best practices
+
+This app depends on \`@guidify-ai/vapi-studio\`. CLI / coding agents **must** read the
+framework best-practice guides before changing conversation copy, agent steps,
+listens, extracts, or identity flows:
+
+- \`node_modules/@guidify-ai/vapi-studio/docs/best-practices/README.md\`
+- \`node_modules/@guidify-ai/vapi-studio/agent/AGENTS.md\`
+- Cursor rule: \`.cursor/rules/vapi-studio-best-practices.mdc\` (installed with the package)
+- Cursor rule: \`.cursor/rules/ui-and-api-identity.mdc\` (UUID externally; \`id\`+\`uuid\` in DB; human \`label\`)
+- Claude Code: \`CLAUDE.md\` + \`.claude/rules/\` (same doctrine; installed with the package)
+
+Hard rules (summary): **one CTA per turn**; conversations **must end** (limits always on);
+constrained fields **fail closed**; short listen timeouts for digits; never store ASR junk
+as PII; soft affirmatives on multi-choice → local re-ask; silent handoffs;
+**async prep/teardown in before()/after()** (do not overload run()); FE uses **uuid**
+only (never internal id) and DTOs include human **label**; update the matching doc layer in the
+same change. Runtime contracts: \`docs/reference/runtime-api.md\`.
+${END}
+`;
+
+const CLAUDE_BEGIN = '<!-- VAPI-STUDIO-CLAUDE:BEGIN -->';
+const CLAUDE_END = '<!-- VAPI-STUDIO-CLAUDE:END -->';
+
+const claudeBlock = `${CLAUDE_BEGIN}
+# Vapi Studio (Claude Code)
+
+Import the shared agent handbook (same content Cursor loads via AGENTS.md):
+
+@node_modules/@guidify-ai/vapi-studio/agent/AGENTS.md
+
+Rules installed by postinstall:
+
+- \`.claude/rules/vapi-studio-best-practices.md\`
+- \`.claude/rules/ui-and-api-identity.md\`
+
+Doctrine index: \`node_modules/@guidify-ai/vapi-studio/docs/best-practices/README.md\`.
+${CLAUDE_END}
+`;
+
+function writeCursorRules() {
+  const destDir = path.join(consumerRoot, '.cursor', 'rules');
+  fs.mkdirSync(destDir, { recursive: true });
+  const files = [
+    'vapi-studio-best-practices.mdc',
+    'ui-and-api-identity.mdc',
+  ];
+  for (const name of files) {
+    const src = path.join(pkgRoot, 'agent', 'cursor', name);
+    const dest = path.join(destDir, name);
+    if (!fs.existsSync(src)) {
+      console.warn('[vapi-studio] agent cursor rule template missing:', name);
+      continue;
+    }
+    fs.copyFileSync(src, dest);
+    console.log('[vapi-studio] wrote', path.relative(consumerRoot, dest) || dest);
+  }
+}
+
+function writeClaudeRules() {
+  const destDir = path.join(consumerRoot, '.claude', 'rules');
+  fs.mkdirSync(destDir, { recursive: true });
+  const files = [
+    'vapi-studio-best-practices.md',
+    'ui-and-api-identity.md',
+  ];
+  for (const name of files) {
+    const src = path.join(pkgRoot, 'agent', 'claude', 'rules', name);
+    const dest = path.join(destDir, name);
+    if (!fs.existsSync(src)) {
+      console.warn('[vapi-studio] agent claude rule template missing:', name);
+      continue;
+    }
+    fs.copyFileSync(src, dest);
+    console.log('[vapi-studio] wrote', path.relative(consumerRoot, dest) || dest);
+  }
+}
+
+function upsertMarkdownBlock(destPath, begin, end, block, emptyTitle) {
+  let existing = '';
+  if (fs.existsSync(destPath)) {
+    existing = fs.readFileSync(destPath, 'utf8');
+  }
+
+  const blockPattern = new RegExp(
+    `${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}`,
+  );
+
+  if (blockPattern.test(existing)) {
+    const next = existing.replace(blockPattern, block.trim());
+    fs.writeFileSync(destPath, ensureTrailingNewline(next));
+    console.log('[vapi-studio] refreshed', path.basename(destPath), 'block');
+    return;
+  }
+
+  if (!existing.trim()) {
+    fs.writeFileSync(
+      destPath,
+      ensureTrailingNewline(`${emptyTitle}\n\n${block}\n`),
+    );
+    console.log('[vapi-studio] created', path.basename(destPath));
+    return;
+  }
+
+  fs.writeFileSync(
+    destPath,
+    ensureTrailingNewline(`${existing.trimEnd()}\n\n${block}\n`),
+  );
+  console.log('[vapi-studio] appended block to', path.basename(destPath));
+}
+
+function upsertAgentsMd() {
+  upsertMarkdownBlock(
+    path.join(consumerRoot, 'AGENTS.md'),
+    BEGIN,
+    END,
+    agentsBlock,
+    '# Agents\n\nProject-specific agent notes for this app.',
+  );
+}
+
+function upsertClaudeMd() {
+  upsertMarkdownBlock(
+    path.join(consumerRoot, 'CLAUDE.md'),
+    CLAUDE_BEGIN,
+    CLAUDE_END,
+    claudeBlock,
+    '# Agents\n\nProject notes for Claude Code. Shared handbook is imported below.',
+  );
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureTrailingNewline(s) {
+  return s.endsWith('\n') ? s : `${s}\n`;
+}
+
+try {
+  writeCursorRules();
+  writeClaudeRules();
+  upsertAgentsMd();
+  upsertClaudeMd();
+} catch (err) {
+  console.warn('[vapi-studio] install-agent-refs failed (non-fatal):', err.message);
+  process.exit(0);
+}