docs: add survey guide

Author: raksiv

docs/guides/nodejs/survey-application.mdx

@@ -0,0 +1,271 @@
+---
+description: Build a serverless backend for capturing and delivering survey submissions using Nitric and TypeScript.
+title_seo: Building a Survey Backend with Nitric and TypeScript
+tags:
+  - API
+  - Event
+  - PDF
+languages:
+  - typescript
+  - javascript
+published_at: 2025-04-03
+updated_at: 2025-04-03
+---
+
+# Building a Survey Backend with Nitric and TypeScript
+
+This guide shows you how to build a backend for capturing, storing, and delivering survey responses using the Nitric framework. The application accepts survey submissions, generates PDF receipts, and delivers them asynchronously.
+
+## API Overview
+
+| **Method** | **Route**       | **Description**                      |
+| ---------- | --------------- | ------------------------------------ |
+| `POST`     | /forms/[formId] | Submit a response to a specific form |
+| `GET`      | /receipts/[id]  | Retrieve a generated receipt by ID   |
+
+Under the hood, the system also handles events via topics and handlers for generating PDFs and delivering them.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/)
+- The [Nitric CLI](/get-started/installation)
+
+## Project Setup
+
+Create a new Nitric project using the TypeScript starter:
+
+```bash
+nitric new surveys-backend ts-starter
+cd surveys-backend
+npm install
+```
+
+## Add Runtime Type Safety
+
+This project uses:
+
+- [Zod](https://zod.dev/) to define and validate the structure of form submissions.
+- [pdfkit](https://pdfkit.org/) to generate pdfs from html templates.
+
+### Install Zod
+
+```bash
+npm install zod pdfkit
+```
+
+### Define a schema for form submissions
+
+Create a file at `src/forms/form/schema.ts`:
+
+```ts title:src/forms/form/schema.ts
+import { z } from 'zod'
+
+export const SubmissionSchema = z.object({
+  name: z.string(),
+  rating: z.number().min(1).max(5),
+  feedback: z.string().optional(),
+})
+
+export type Submission = z.infer<typeof SubmissionSchema>
+```
+
+This schema ensures that any incoming submission contains a valid name, a 1–5 rating, and optional feedback.
+
+## Step 1: Define Resources
+
+Create and configure the cloud resources your backend will use, such as storage buckets, queues, and key-value stores.
+
+```ts title:src/resources/resources.ts
+import { bucket, kv, topic } from '@nitric/sdk'
+
+export const output = bucket('receipts').allow('read', 'write')
+export const submissions = kv('submissions').allow('set', 'get')
+export const submitted = topic('form-submitted').allow('publish')
+export const receipts = topic('form-submitted')
+```
+
+## Step 2: Handle Submissions
+
+Create an API route that validates and stores form submissions, then triggers further processing.
+
+```ts title:src/services/forms.ts
+import { api } from '@nitric/sdk'
+import { submissions, submitted } from '../resources/resources'
+import { SubmissionSchema } from '../form/schema'
+
+const formApi = api('forms')
+
+formApi.post('/forms/:formId', async (ctx) => {
+  const formId = ctx.req.params.formId
+  const parsed = SubmissionSchema.safeParse(ctx.req.json())
+  if (!parsed.success) {
+    ctx.res.status = 400
+    ctx.res.json({ msg: 'Invalid submission', errors: parsed.error.format() })
+    return
+  }
+  const data = parsed.data
+  const id = `${formId}-${Date.now()}`
+
+  await submissions.set(id, data)
+  await submitted.publish({ id, formId })
+
+  ctx.res.json({ msg: 'Submission received', id })
+})
+```
+
+## Step 3: Generate PDF Receipts
+
+Listen for submitted events and generate a formatted PDF receipt from the stored data.
+
+```ts title:src/services/pdfs.ts
+import { receipts, submissions, output } from '../resources/resources'
+import { buildReceipt } from '../form/receipt'
+
+receipts.subscribe(async (ctx) => {
+  const { id } = ctx.req.json()
+  const submission = await submissions.get(id)
+
+  if (!submission) {
+    console.error(`No submission found for ID: ${id}`)
+    return
+  }
+
+  // Build the PDF buffer from the submission data
+  const buffer = await buildReceipt(submission)
+
+  // Store the PDF file in the bucket
+  const file = output.file(`${id}.pdf`)
+  await file.write(buffer)
+
+  console.log(`Receipt stored for ${id}`)
+})
+```
+
+### Build the PDF Receipt
+
+```ts title:src/forms/form/receipt.ts
+import PDFDocument from 'pdfkit'
+import { Submission } from './schema'
+
+export const buildReceipt = async (data: Submission) => {
+  const receipt = new PDFDocument({ bufferPages: true })
+
+  const doneWriting = new Promise<Buffer>((resolve) => {
+    const buffers: Uint8Array[] = []
+
+    // Collect PDF output in memory as chunks
+    receipt.on('data', buffers.push.bind(buffers))
+    receipt.on('end', () => {
+      const pdfData = Buffer.concat(buffers)
+      resolve(pdfData)
+    })
+
+    const { name, rating, feedback } = data
+
+    // Write header
+    receipt.font('Times-Roman').fontSize(20).text('Survey - Receipt', 100, 100)
+
+    // Write section title
+    receipt
+      .font('Times-Roman')
+      .fontSize(16)
+      .text('Primary Applicant Details', 100, 150)
+
+    // Write submission details
+    receipt
+      .font('Times-Roman')
+      .fontSize(12)
+      .text(
+        `Name: ${name}
+Rating: ${rating}
+Feedback: ${feedback || 'N/A'}`,
+        100,
+        175,
+      )
+
+    // Finalize the PDF
+    receipt.end()
+  })
+
+  return await doneWriting
+}
+```
+
+This PDF output is fairly plain, you can enhance it further using layout templates or branding.
+
+## Step 4: Delivery Logic
+
+Simulate or perform delivery of the receipt (e.g. via email or other downstream systems).
+
+```ts title:src/services/deliver.ts
+import { receipts } from '../resources/resources'
+
+receipts.subscribe(async (ctx) => {
+  const { id } = ctx.req.json()
+
+  // Handle delivery or hook into a real email/SaaS integration
+  console.log(`Delivering receipt for submission: ${id}`)
+})
+```
+
+## Step 5: Retrieve Receipts
+
+Create an endpoint that returns a download URL for the generated receipt file.
+
+```ts title:src/apis/receipts.ts
+import { api } from '@nitric/sdk'
+import { output } from '../resources/resources'
+
+const receiptApi = api('receipts')
+
+receiptApi.get('/receipts/:id', async (ctx) => {
+  const id = ctx.req.params.id
+  const file = output.file(`${id}.pdf`)
+  const url = await file.getDownloadUrl()
+  ctx.res.body = url
+})
+```
+
+## Run and Test Locally
+
+```bash
+nitric start
+```
+
+### Submit a Survey
+
+Use the dashboard to submit your survey data -
+
+```json
+{
+  "name": "Jane",
+  "rating": 5,
+  "feedback": "Great experience!"
+}
+```
+
+![Submit Form](/docs/images/guides/survey-application/submit.png)
+
+You should see messages in your console for PDF generation and delivery.
+
+### Get a Receipt
+
+Replace `<timestamp>` with the value returned from the submission.
+
+![Get receipt](/docs/images/guides/survey-application/receipt.png)
+
+Use the URL in the response to retrieve your PDF:
+
+![Get PDF](/docs/images/guides/survey-application/pdf.png)
+
+## Summary
+
+In this guide, you built a backend for handling survey submissions using Nitric and TypeScript:
+
+- Created a REST API to accept form submissions
+- Validated user input using Zod
+- Stored submissions in a key-value store
+- Generated PDF receipts using pdfkit
+- Stored the receipts in cloud storage
+- Delivered them asynchronously via event topics
+- Exposed a URL endpoint to retrieve generated receipts