added Quickstart

Author: vanderbr

README.md

@@ -19,19 +19,7 @@ TypeScript server SDK for age verification, designed to help websites implement
 pnpm add @agecheck/node
 ```
 
-## Runtime requirement
-
-- Node.js `>=20`
-
-## Required environment variables
-
-```bash
-AGECHECK_COOKIE_SECRET=replace_with_32_plus_bytes_random
-AGECHECK_DEPLOYMENT_MODE=production
-AGECHECK_REQUIRED_AGE=18
-AGECHECK_GATE_HEADER_NAME=X-Age-Gate
-AGECHECK_GATE_HEADER_REQUIRED_VALUE=true
-```
+Quickstart: see `/docs/QUICKSTART.md`.
 
 ## Supported integration modes
 

docs/QUICKSTART.md

@@ -0,0 +1,52 @@
+# Quickstart
+
+Use this page for shared runtime and configuration requirements across all Node framework adapters.
+
+## Runtime
+
+- Node.js `>=20`
+
+## Required environment variables
+
+```bash
+AGECHECK_COOKIE_SECRET=replace_with_32_plus_bytes_random
+AGECHECK_DEPLOYMENT_MODE=production
+AGECHECK_REQUIRED_AGE=18
+AGECHECK_GATE_HEADER_NAME=X-Age-Gate
+AGECHECK_GATE_HEADER_REQUIRED_VALUE=true
+```
+
+Notes:
+- `AGECHECK_COOKIE_SECRET` must be at least 32 bytes.
+- `AGECHECK_DEPLOYMENT_MODE`:
+  - `production`: accepts production issuer credentials and raises gate only when header policy requires it
+  - `demo`: accepts demo + production issuer credentials and always raises gate
+
+## Recommended pattern
+
+Use framework adapter handlers for verify and gate enforcement:
+
+- Express: `createExpressVerifyHandler`, `createExpressGateMiddleware`
+- Fastify: `createFastifyVerifyHandler`, `createFastifyGateHook`
+- Hono: `createHonoVerifyHandler`, `createHonoGateMiddleware`
+- Nuxt: `createNuxtVerifyHandler`, `createNuxtGateMiddleware`
+
+Most hostmasters should not manually call low-level cookie helpers.
+
+## Troubleshooting
+
+If verify response shows:
+
+```json
+{
+  "verified": false,
+  "code": "verify_failed",
+  "error": "Failed to issue verification cookie"
+}
+```
+
+check:
+- Node runtime is `>=20`
+- `AGECHECK_COOKIE_SECRET` is present in the running process and is at least 32 bytes
+- request contains `payload.agegateway_session` as a UUID
+- you are using adapter handlers instead of manual cookie issuance paths

docs/frameworks/express.md

@@ -1,5 +1,7 @@
 # Express Integration
 
+Prerequisites: see `/docs/QUICKSTART.md`.
+
 ```ts
 import express from "express";
 import {
@@ -28,13 +30,3 @@ app.get("/restricted", (_req, res) => {
   res.status(200).send("Restricted content");
 });
 ```
-
-Required environment variables:
-
-```bash
-AGECHECK_COOKIE_SECRET=replace_with_32_plus_bytes_random
-AGECHECK_DEPLOYMENT_MODE=production
-AGECHECK_REQUIRED_AGE=18
-AGECHECK_GATE_HEADER_NAME=X-Age-Gate
-AGECHECK_GATE_HEADER_REQUIRED_VALUE=true
-```

docs/frameworks/fastify.md

@@ -1,5 +1,7 @@
 # Fastify Integration
 
+Prerequisites: see `/docs/QUICKSTART.md`.
+
 ```ts
 import Fastify from "fastify";
 import {
@@ -11,9 +13,12 @@ import {
 const fastify = Fastify();
 
 const sdk = new AgeCheckSdk({
-  deploymentMode: "production",
-  verify: { requiredAge: 18 },
-  gate: { headerName: "X-Age-Gate", requiredValue: "true" },
+  deploymentMode: process.env.AGECHECK_DEPLOYMENT_MODE === "demo" ? "demo" : "production",
+  verify: { requiredAge: Number(process.env.AGECHECK_REQUIRED_AGE ?? "18") },
+  gate: {
+    headerName: process.env.AGECHECK_GATE_HEADER_NAME ?? "X-Age-Gate",
+    requiredValue: process.env.AGECHECK_GATE_HEADER_REQUIRED_VALUE ?? "true",
+  },
   cookie: { secret: process.env.AGECHECK_COOKIE_SECRET!, cookieName: "agecheck_verified", ttlSeconds: 86400 },
 });
 

docs/frameworks/hono.md

@@ -1,5 +1,7 @@
 # Hono Integration
 
+Prerequisites: see `/docs/QUICKSTART.md`.
+
 ```ts
 import { Hono } from "hono";
 import {
@@ -11,9 +13,12 @@ import {
 const app = new Hono();
 
 const sdk = new AgeCheckSdk({
-  deploymentMode: "production",
-  verify: { requiredAge: 18 },
-  gate: { headerName: "X-Age-Gate", requiredValue: "true" },
+  deploymentMode: process.env.AGECHECK_DEPLOYMENT_MODE === "demo" ? "demo" : "production",
+  verify: { requiredAge: Number(process.env.AGECHECK_REQUIRED_AGE ?? "18") },
+  gate: {
+    headerName: process.env.AGECHECK_GATE_HEADER_NAME ?? "X-Age-Gate",
+    requiredValue: process.env.AGECHECK_GATE_HEADER_REQUIRED_VALUE ?? "true",
+  },
   cookie: { secret: process.env.AGECHECK_COOKIE_SECRET!, cookieName: "agecheck_verified", ttlSeconds: 86400 },
 });
 

docs/frameworks/nuxt.md

@@ -1,5 +1,7 @@
 # Nuxt Server Integration
 
+Prerequisites: see `/docs/QUICKSTART.md`.
+
 ```ts
 // server/middleware/agecheck.ts
 import {
@@ -8,9 +10,12 @@ import {
 } from "@agecheck/node";
 
 const sdk = new AgeCheckSdk({
-  deploymentMode: "production",
-  verify: { requiredAge: 18 },
-  gate: { headerName: "X-Age-Gate", requiredValue: "true" },
+  deploymentMode: process.env.AGECHECK_DEPLOYMENT_MODE === "demo" ? "demo" : "production",
+  verify: { requiredAge: Number(process.env.AGECHECK_REQUIRED_AGE ?? "18") },
+  gate: {
+    headerName: process.env.AGECHECK_GATE_HEADER_NAME ?? "X-Age-Gate",
+    requiredValue: process.env.AGECHECK_GATE_HEADER_REQUIRED_VALUE ?? "true",
+  },
   cookie: { secret: process.env.AGECHECK_COOKIE_SECRET!, cookieName: "agecheck_verified", ttlSeconds: 86400 },
 });
 
@@ -31,9 +36,12 @@ import {
 } from "@agecheck/node";
 
 const sdk = new AgeCheckSdk({
-  deploymentMode: "production",
-  verify: { requiredAge: 18 },
-  gate: { headerName: "X-Age-Gate", requiredValue: "true" },
+  deploymentMode: process.env.AGECHECK_DEPLOYMENT_MODE === "demo" ? "demo" : "production",
+  verify: { requiredAge: Number(process.env.AGECHECK_REQUIRED_AGE ?? "18") },
+  gate: {
+    headerName: process.env.AGECHECK_GATE_HEADER_NAME ?? "X-Age-Gate",
+    requiredValue: process.env.AGECHECK_GATE_HEADER_REQUIRED_VALUE ?? "true",
+  },
   cookie: { secret: process.env.AGECHECK_COOKIE_SECRET!, cookieName: "agecheck_verified", ttlSeconds: 86400 },
 });