# Quickstart This guide uses the framework packages users should install directly: Next.js, Express, Hono, Fastify, Bun, Deno, NestJS, SvelteKit, Go, Python, and Rust, plus the core package and backend contract for custom services. ## 1. Prerequisites - Node.js 20 or newer. - A runtime API key with the scopes your route will use. - Optional local API origin override only when you are testing against a non-production gateway. ## 2. Install The Package For Your Stack ``bash pnpm add @cosantoir/next # or pnpm add @cosantoir/express # or pnpm add @cosantoir/hono # or pnpm add @cosantoir/fastify # or pnpm add @cosantoir/bun # or pnpm add @cosantoir/nestjs # or pnpm add @cosantoir/sveltekit # Deno users can import npm:@cosantoir/deno directly. ` Use the core package only when you are writing your own adapter or direct runtime calls: `bash pnpm add @cosantoir/node ` For non-JavaScript services, install the native package for the ecosystem: `bash go get github.com/cosantoir/cosantoir-go pip install cosantoir cargo add cosantoir ` Any service can also integrate directly against the runtime backend contract if you already have your own middleware layer. ## 3. Configure Environment Variables `bash export COSANTOIR_API_KEY=dp_live_example ` The API key maps the request to the billable Cosantoir workspace, project, site, environment, and policy. Your own app user is passed separately as userId on middleware or runtime calls. ## 4. Choose Your Integration Path ### Next.js Use the Next adapter when you want proxy-based protection and App Router route handlers. `ts import { createCosantoir, createDeveloperProtectionMiddleware, readNextRequestIp } from "@cosantoir/next"; const client = createCosantoir({ apiKey: process.env.COSANTOIR_API_KEY!, }); export const proxy = createDeveloperProtectionMiddleware({ client, failOpen: true, ip: (request) => readNextRequestIp(request) ?? "127.0.0.1", userId: (request) => request.headers.get("x-user-id"), }); export const config = { matcher: ["/api/protected/:path*"], }; ` ### Express Use the Express adapter when you need runtime enforcement inside an existing Node server. `ts import express from "express"; import { createCosantoir, createDeveloperProtectionExpressMiddleware } from "@cosantoir/express"; const client = createCosantoir({ apiKey: process.env.COSANTOIR_API_KEY!, }); const app = express(); app.use(express.json()); app.use( "/protected", createDeveloperProtectionExpressMiddleware({ client, userId: (request) => String(request.headers["x-user-id"] ?? ""), }) ); ` ### Hono Use the Hono adapter when you want a small Fetch-native runtime surface. `ts import { Hono } from "hono"; import { createCosantoir, createDeveloperProtectionHonoMiddleware } from "@cosantoir/hono"; const client = createCosantoir({ apiKey: process.env.COSANTOIR_API_KEY!, }); const app = new Hono(); app.use( "/protected/*", createDeveloperProtectionHonoMiddleware({ client, userId: (context) => context.req.header("x-user-id"), }) ); ` ### Direct Runtime Calls Use direct calls when your SaaS app wants an explicit product event around one user action. `ts import { createCosantoir } from "@cosantoir/node"; const cosantoir = createCosantoir({ apiKey: process.env.COSANTOIR_API_KEY!, }); await cosantoir.rateLimit.consume({ ip: "198.51.100.20", method: "POST", path: "/api/checkout", userId: "user_123", }); ` Use a stable internal id such as user_123, org_456, or tenant_abc. Avoid raw email addresses unless your own data policy allows PII in runtime telemetry. ### Go, Python, And Rust Services Use the native SDKs when your backend owns request middleware outside the JavaScript runtime. - Go: go get github.com/cosantoir/cosantoir-go. - Python: pip install cosantoir. - Rust: cargo add cosantoir. - Each SDK sends signed requests to the module routes under /v1/dev/*. - Pass COSANTOIR_API_KEY from your runtime environment. The production API origin is the SDK default; set a base URL only for local or staging overrides. - Pass user_id or UserID from your app session, account, tenant, or organization model. - On Google Cloud Run, keep those values in service env vars or secret-backed config and forward the real client IP from your edge or gateway. ## 5. Verify A Protected Route Run a request through the route you protected. `bash curl -X POST http://localhost:3000/protected/signup \ -H 'content-type: application/json' \ -H 'x-forwarded-for: 198.51.100.20' \ -d '{"email":"founder@example.com"}' ` ## 6. Confirm Runtime Behavior - 200 on allowed traffic. - 429 with Retry-After when rate limiting blocks. - 403 when WAF blocks or challenges the request. - Decision records in the developer dashboard and analytics endpoints. - Decision events with event.subject.user_id and subject_user_id when userId is present. ## 7. Continue With Module-Specific Tuning - Tune request budgets in the rate-limit module. - Add managed or custom WAF rules. - Review IP, email, signup, and bot decision trails. - Use the API key for Cosantoir billing and policy identity, and userId` for your SaaS customer identity. > If the route does not behave as expected, continue with Troubleshooting.