@constructive-io/send-verification-link-fn

Knative-compatible email link function used with the Constructive jobs system. It is designed to be invoked by @constructive-io/knative-job-worker as an HTTP function named send-verification-link.

The function:

• Reads metadata about the tenant/site from a GraphQL API
• Generates a styled HTML email using @launchql/mjml
• Sends the email via @launchql/postmaster
• Supports invite, password reset, and email verification flows

Expected job payload

Jobs should use task_identifier = 'email:send_verification_link' and a JSON payload like:

{
  "email_type": "invite_email",
  "email": "user@example.com",
  "invite_token": "abc123",
  "sender_id": "00000000-0000-0000-0000-000000000001"
}

Supported email_type values and parameters:

• invite_email
  • email (string, required)
  • invite_token (string, required)
  • sender_id (UUID string, required)
• forgot_password
  • email (string, required)
  • user_id (UUID string, required)
  • reset_token (string, required)
• email_verification
  • email (string, required)
  • email_id (UUID string, required)
  • verification_token (string, required)

If required fields are missing the function returns a small JSON object like:

{ "missing": "email_type" }

HTTP contract (with knative-job-worker)

The function is wrapped by @constructive-io/knative-job-fn, so it expects:

• HTTP method: POST
• Body: JSON job payload (see above)
• Headers (set by @constructive-io/knative-job-worker):
  • X-Worker-Id
  • X-Job-Id
  • X-Database-Id
  • X-Callback-Url

The handler will:

1. Resolve the tenant/site by databaseId via GraphQL
2. Generate an email link and HTML via @launchql/mjml
3. Send the email with @launchql/postmaster
4. Respond with HTTP 200 and JSON:

{ "complete": true }

Errors are propagated through the Express error middleware installed by @constructive-io/knative-job-fn, so they can be translated into X-Job-Error callbacks by your gateway/callback server.

Environment variables

Required:

• GRAPHQL_URL
  GraphQL endpoint for the tenant database (for GetUser and/or per-tenant data).

Recommended / optional:

• META_GRAPHQL_URL
  GraphQL endpoint for meta/database-level schema. Defaults to GRAPHQL_URL when not set.
• GRAPHQL_AUTH_TOKEN
  Bearer token to send as Authorization header for GraphQL requests.
• DEFAULT_DATABASE_ID
  Used if X-Database-Id is not provided by the worker. In normal jobs usage, X-Database-Id should always be present.
• LOCAL_APP_PORT
  Optional port suffix for localhost-style hosts (e.g. 3000). When the resolved hostname is localhost / *.localhost and SEND_VERIFICATION_LINK_DRY_RUN=true, links are generated as http://localhost:LOCAL_APP_PORT/.... Ignored for non-local hostnames and in production.

Email delivery (default: @launchql/postmaster):

• Set EMAIL_SEND_USE_SMTP=true to switch to simple-smtp-server (SMTP). Otherwise it uses @launchql/postmaster.

• Mailgun or another provider; consult @launchql/postmaster docs. A common pattern is:

  • MAILGUN_API_KEY
  • MAILGUN_DOMAIN
  • MAILGUN_FROM

• SMTP variables when EMAIL_SEND_USE_SMTP=true:

  • SMTP_HOST
  • SMTP_PORT
  • SMTP_USER
  • SMTP_PASS
  • SMTP_FROM

Building locally

From the repo root:

pnpm --filter="@constructive-io/send-verification-link-fn" build

This compiles TypeScript into dist/.

Dockerfile

The function is intended to be containerized and run as a Knative Service. A minimal Dockerfile:

FROM node:18-alpine

WORKDIR /usr/src/app

# Install production dependencies
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm@9 && pnpm install --prod

# Copy compiled code
COPY dist ./dist

ENV NODE_ENV=production
ENV PORT=8080

CMD ["node", "dist/index.js"]

Build and push:

pnpm --filter="@constructive-io/send-verification-link-fn" build
docker build -t your-registry/send-verification-link-fn:latest functions/send-verification-link
docker push your-registry/send-verification-link-fn:latest

Example Knative Service

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: send-verification-link
  namespace: default
spec:
  template:
    spec:
      containers:
        - image: your-registry/send-verification-link-fn:latest
          env:
            - name: GRAPHQL_URL
              value: "https://api.your-domain.com/graphql"
            - name: META_GRAPHQL_URL
              value: "https://meta-api.your-domain.com/graphql"
            - name: GRAPHQL_AUTH_TOKEN
              valueFrom:
                secretKeyRef:
                  name: graphql-auth
                  key: token
            # MAILGUN / Postmaster config here...
            - name: MAILGUN_API_KEY
              valueFrom:
                secretKeyRef:
                  name: mailgun
                  key: api-key

Once deployed, point @constructive-io/knative-job-worker at this service by configuring:

• KNATIVE_SERVICE_URL to route /send-verification-link to this function
• JOBS_SUPPORTED=send-verification-link (or JOBS_SUPPORT_ANY=true)

Education and Tutorials

1. 🚀 Quickstart: Getting Up and Running Get started with modular databases in minutes. Install prerequisites and deploy your first module.

2. 📦 Modular PostgreSQL Development with Database Packages Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.

3. ✏️ Authoring Database Changes Master the workflow for adding, organizing, and managing database changes with pgpm.

4. 🧪 End-to-End PostgreSQL Testing with TypeScript Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.

5. ⚡ Supabase Testing Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.

6. 💧 Drizzle ORM Testing Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.

7. 🔧 Troubleshooting Common issues and solutions for pgpm, PostgreSQL, and testing.

Related Constructive Tooling

📦 Package Management

• pgpm: 🖥️ PostgreSQL Package Manager for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.

🧪 Testing

• pgsql-test: 📊 Isolated testing environments with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
• pgsql-seed: 🌱 PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
• supabase-test: 🧪 Supabase-native test harness preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
• graphile-test: 🔐 Authentication mocking for Graphile-focused test helpers and emulating row-level security contexts.
• pg-query-context: 🔒 Session context injection to add session-local context (e.g., SET LOCAL) into queries—ideal for setting role, jwt.claims, and other session settings.

🧠 Parsing & AST

• pgsql-parser: 🔄 SQL conversion engine that interprets and converts PostgreSQL syntax.
• libpg-query-node: 🌉 Node.js bindings for libpg_query, converting SQL into parse trees.
• pg-proto-parser: 📦 Protobuf parser for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
• @pgsql/enums: 🏷️ TypeScript enums for PostgreSQL AST for safe and ergonomic parsing logic.
• @pgsql/types: 📝 Type definitions for PostgreSQL AST nodes in TypeScript.
• @pgsql/utils: 🛠️ AST utilities for constructing and transforming PostgreSQL syntax trees.

Credits

🛠 Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.