@constructive-io/send-email-link-fn 0.3.1

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @constructive-io/send-email-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-email-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 = 'send-email-link'` and a JSON payload like:
+
+```json
+{
+  "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:
+
+```json
+{ "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:
+
+```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_EMAIL_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:
+
+```bash
+pnpm --filter="@constructive-io/send-email-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:
+
+```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:
+
+```bash
+pnpm --filter="@constructive-io/send-email-link-fn" build
+docker build -t your-registry/send-email-link-fn:latest functions/send-email-link
+docker push your-registry/send-email-link-fn:latest
+```
+
+## Example Knative Service
+
+```yaml
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: send-email-link
+  namespace: default
+spec:
+  template:
+    spec:
+      containers:
+        - image: your-registry/send-email-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-email-link` to this function
+- `JOBS_SUPPORTED=send-email-link` (or `JOBS_SUPPORT_ANY=true`)
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/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](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/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](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## 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.

package/esm/index.js

@@ -0,0 +1,277 @@
+import { createJobApp } from '@constructive-io/knative-job-fn';
+import { GraphQLClient } from 'graphql-request';
+import gql from 'graphql-tag';
+import { generate } from '@launchql/mjml';
+import { send as sendPostmaster } from '@launchql/postmaster';
+import { send as sendSmtp } from 'simple-smtp-server';
+import { parseEnvBoolean } from '@pgpmjs/env';
+import { createLogger } from '@pgpmjs/logger';
+const isDryRun = parseEnvBoolean(process.env.SEND_EMAIL_LINK_DRY_RUN) ?? false;
+const useSmtp = parseEnvBoolean(process.env.EMAIL_SEND_USE_SMTP) ?? false;
+const logger = createLogger('send-email-link');
+const app = createJobApp();
+const GetUser = gql `
+  query GetUser($userId: UUID!) {
+    user(id: $userId) {
+      username
+      displayName
+      profilePicture
+    }
+  }
+`;
+const GetDatabaseInfo = gql `
+  query GetDatabaseInfo($databaseId: UUID!) {
+    database(id: $databaseId) {
+      sites {
+        nodes {
+          domains {
+            nodes {
+              subdomain
+              domain
+            }
+          }
+          logo
+          title
+          siteThemes {
+            nodes {
+              theme
+            }
+          }
+          siteModules(condition: { name: "legal_terms_module" }) {
+            nodes {
+              data
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+const getRequiredEnv = (name) => {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable ${name}`);
+    }
+    return value;
+};
+const createGraphQLClient = (url, hostHeaderEnvVar) => {
+    const headers = {};
+    if (process.env.GRAPHQL_AUTH_TOKEN) {
+        headers.Authorization = `Bearer ${process.env.GRAPHQL_AUTH_TOKEN}`;
+    }
+    const envName = hostHeaderEnvVar || 'GRAPHQL_HOST_HEADER';
+    const hostHeader = process.env[envName];
+    if (hostHeader) {
+        headers.host = hostHeader;
+    }
+    return new GraphQLClient(url, { headers });
+};
+export const sendEmailLink = async (params, context) => {
+    const { client, meta, databaseId } = context;
+    const validateForType = () => {
+        switch (params.email_type) {
+            case 'invite_email':
+                if (!params.invite_token || !params.sender_id) {
+                    return { missing: 'invite_token_or_sender_id' };
+                }
+                return null;
+            case 'forgot_password':
+                if (!params.user_id || !params.reset_token) {
+                    return { missing: 'user_id_or_reset_token' };
+                }
+                return null;
+            case 'email_verification':
+                if (!params.email_id || !params.verification_token) {
+                    return { missing: 'email_id_or_verification_token' };
+                }
+                return null;
+            default:
+                return { missing: 'email_type' };
+        }
+    };
+    if (!params.email_type) {
+        return { missing: 'email_type' };
+    }
+    if (!params.email) {
+        return { missing: 'email' };
+    }
+    const typeValidation = validateForType();
+    if (typeValidation) {
+        return typeValidation;
+    }
+    const databaseInfo = await meta.request(GetDatabaseInfo, {
+        databaseId
+    });
+    const site = databaseInfo?.database?.sites?.nodes?.[0];
+    if (!site) {
+        throw new Error('Site not found for database');
+    }
+    const legalTermsModule = site.siteModules?.nodes?.[0];
+    const domainNode = site.domains?.nodes?.[0];
+    const theme = site.siteThemes?.nodes?.[0]?.theme;
+    if (!legalTermsModule || !domainNode || !theme) {
+        throw new Error('Missing site configuration for email');
+    }
+    const subdomain = domainNode.subdomain;
+    const domain = domainNode.domain;
+    const supportEmail = legalTermsModule.data.emails.support;
+    const logo = site.logo?.url;
+    const company = legalTermsModule.data.company;
+    const website = company.website;
+    const nick = company.nick;
+    const name = company.name;
+    const primary = theme.primary;
+    const hostname = subdomain ? [subdomain, domain].join('.') : domain;
+    // Treat localhost-style hosts specially so we can generate
+    // http://localhost[:port]/... links for local dev without
+    // breaking production URLs.
+    const isLocalHost = hostname.startsWith('localhost') ||
+        hostname.startsWith('0.0.0.0') ||
+        hostname.endsWith('.localhost');
+    // Optional: LOCAL_APP_PORT lets you attach a port for local dashboards
+    // e.g. LOCAL_APP_PORT=3000 -> http://localhost:3000
+    // It is ignored for non-local hostnames. Only allow on DRY RUNs
+    const localPort = isLocalHost && isDryRun && process.env.LOCAL_APP_PORT
+        ? `:${process.env.LOCAL_APP_PORT}`
+        : '';
+    // Use http only for local dry-run to avoid browser TLS warnings
+    // in dev; production stays https.
+    const protocol = isLocalHost && isDryRun ? 'http' : 'https';
+    const url = new URL(`${protocol}://${hostname}${localPort}`);
+    let subject;
+    let subMessage;
+    let linkText;
+    let inviterName;
+    switch (params.email_type) {
+        case 'invite_email': {
+            if (!params.invite_token || !params.sender_id) {
+                return { missing: 'invite_token_or_sender_id' };
+            }
+            url.pathname = 'register';
+            url.searchParams.append('invite_token', params.invite_token);
+            url.searchParams.append('email', params.email);
+            const scope = Number(params.invite_type) === 2 ? 'org' : 'app';
+            url.searchParams.append('type', scope);
+            const inviter = await client.request(GetUser, {
+                userId: params.sender_id
+            });
+            inviterName = inviter?.user?.displayName;
+            if (inviterName) {
+                subject = `${inviterName} invited you to ${nick}!`;
+                subMessage = `You've been invited to ${nick}`;
+            }
+            else {
+                subject = `Welcome to ${nick}!`;
+                subMessage = `You've been invited to ${nick}`;
+            }
+            linkText = 'Join Us';
+            break;
+        }
+        case 'forgot_password': {
+            if (!params.user_id || !params.reset_token) {
+                return { missing: 'user_id_or_reset_token' };
+            }
+            url.pathname = 'reset-password';
+            url.searchParams.append('role_id', params.user_id);
+            url.searchParams.append('reset_token', params.reset_token);
+            subject = `${nick} Password Reset Request`;
+            subMessage = 'Click below to reset your password';
+            linkText = 'Reset Password';
+            break;
+        }
+        case 'email_verification': {
+            if (!params.email_id || !params.verification_token) {
+                return { missing: 'email_id_or_verification_token' };
+            }
+            url.pathname = 'verify-email';
+            url.searchParams.append('email_id', params.email_id);
+            url.searchParams.append('verification_token', params.verification_token);
+            subject = `${nick} Email Verification`;
+            subMessage = 'Please confirm your email address';
+            linkText = 'Confirm Email';
+            break;
+        }
+        default:
+            return false;
+    }
+    const link = url.href;
+    const html = generate({
+        title: subject,
+        link,
+        linkText,
+        message: subject,
+        subMessage,
+        bodyBgColor: 'white',
+        headerBgColor: 'white',
+        messageBgColor: 'white',
+        messageTextColor: '#414141',
+        messageButtonBgColor: primary,
+        messageButtonTextColor: 'white',
+        companyName: name,
+        supportEmail,
+        website,
+        logo,
+        headerImageProps: {
+            alt: 'logo',
+            align: 'center',
+            border: 'none',
+            width: '162px',
+            paddingLeft: '0px',
+            paddingRight: '0px',
+            paddingBottom: '0px',
+            paddingTop: '0'
+        }
+    });
+    if (isDryRun) {
+        logger.info('DRY RUN email (skipping send)', {
+            email_type: params.email_type,
+            email: params.email,
+            subject,
+            link
+        });
+    }
+    else {
+        const sendEmail = useSmtp ? sendSmtp : sendPostmaster;
+        await sendEmail({
+            to: params.email,
+            subject,
+            html
+        });
+    }
+    return {
+        complete: true,
+        ...(isDryRun ? { dryRun: true } : null)
+    };
+};
+// HTTP/Knative entrypoint (used by @constructive-io/knative-job-fn wrapper)
+app.post('/', async (req, res, next) => {
+    try {
+        const params = (req.body || {});
+        const databaseId = req.get('X-Database-Id') || req.get('x-database-id') || process.env.DEFAULT_DATABASE_ID;
+        if (!databaseId) {
+            return res.status(400).json({ error: 'Missing X-Database-Id header or DEFAULT_DATABASE_ID' });
+        }
+        const graphqlUrl = getRequiredEnv('GRAPHQL_URL');
+        const metaGraphqlUrl = process.env.META_GRAPHQL_URL || graphqlUrl;
+        const client = createGraphQLClient(graphqlUrl, 'GRAPHQL_HOST_HEADER');
+        const meta = createGraphQLClient(metaGraphqlUrl, 'META_GRAPHQL_HOST_HEADER');
+        const result = await sendEmailLink(params, {
+            client,
+            meta,
+            databaseId
+        });
+        res.status(200).json(result);
+    }
+    catch (err) {
+        next(err);
+    }
+});
+export default app;
+// When executed directly (e.g. via `node dist/index.js`), start an HTTP server.
+if (require.main === module) {
+    const port = Number(process.env.PORT ?? 8080);
+    // @constructive-io/knative-job-fn exposes a .listen method that delegates to the Express app
+    app.listen(port, () => {
+        logger.info(`listening on port ${port}`);
+    });
+}

package/index.d.ts

@@ -0,0 +1,25 @@
+import { GraphQLClient } from 'graphql-request';
+declare const app: any;
+type SendEmailParams = {
+    email_type: 'invite_email' | 'forgot_password' | 'email_verification';
+    email: string;
+    invite_type?: number | string;
+    invite_token?: string;
+    sender_id?: string;
+    user_id?: string;
+    reset_token?: string;
+    email_id?: string;
+    verification_token?: string;
+};
+type GraphQLContext = {
+    client: GraphQLClient;
+    meta: GraphQLClient;
+    databaseId: string;
+};
+export declare const sendEmailLink: (params: SendEmailParams, context: GraphQLContext) => Promise<false | {
+    missing?: string;
+} | {
+    dryRun: boolean;
+    complete: boolean;
+}>;
+export default app;

package/index.js

@@ -0,0 +1,284 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendEmailLink = void 0;
+const knative_job_fn_1 = require("@constructive-io/knative-job-fn");
+const graphql_request_1 = require("graphql-request");
+const graphql_tag_1 = __importDefault(require("graphql-tag"));
+const mjml_1 = require("@launchql/mjml");
+const postmaster_1 = require("@launchql/postmaster");
+const simple_smtp_server_1 = require("simple-smtp-server");
+const env_1 = require("@pgpmjs/env");
+const logger_1 = require("@pgpmjs/logger");
+const isDryRun = (0, env_1.parseEnvBoolean)(process.env.SEND_EMAIL_LINK_DRY_RUN) ?? false;
+const useSmtp = (0, env_1.parseEnvBoolean)(process.env.EMAIL_SEND_USE_SMTP) ?? false;
+const logger = (0, logger_1.createLogger)('send-email-link');
+const app = (0, knative_job_fn_1.createJobApp)();
+const GetUser = (0, graphql_tag_1.default) `
+  query GetUser($userId: UUID!) {
+    user(id: $userId) {
+      username
+      displayName
+      profilePicture
+    }
+  }
+`;
+const GetDatabaseInfo = (0, graphql_tag_1.default) `
+  query GetDatabaseInfo($databaseId: UUID!) {
+    database(id: $databaseId) {
+      sites {
+        nodes {
+          domains {
+            nodes {
+              subdomain
+              domain
+            }
+          }
+          logo
+          title
+          siteThemes {
+            nodes {
+              theme
+            }
+          }
+          siteModules(condition: { name: "legal_terms_module" }) {
+            nodes {
+              data
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+const getRequiredEnv = (name) => {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable ${name}`);
+    }
+    return value;
+};
+const createGraphQLClient = (url, hostHeaderEnvVar) => {
+    const headers = {};
+    if (process.env.GRAPHQL_AUTH_TOKEN) {
+        headers.Authorization = `Bearer ${process.env.GRAPHQL_AUTH_TOKEN}`;
+    }
+    const envName = hostHeaderEnvVar || 'GRAPHQL_HOST_HEADER';
+    const hostHeader = process.env[envName];
+    if (hostHeader) {
+        headers.host = hostHeader;
+    }
+    return new graphql_request_1.GraphQLClient(url, { headers });
+};
+const sendEmailLink = async (params, context) => {
+    const { client, meta, databaseId } = context;
+    const validateForType = () => {
+        switch (params.email_type) {
+            case 'invite_email':
+                if (!params.invite_token || !params.sender_id) {
+                    return { missing: 'invite_token_or_sender_id' };
+                }
+                return null;
+            case 'forgot_password':
+                if (!params.user_id || !params.reset_token) {
+                    return { missing: 'user_id_or_reset_token' };
+                }
+                return null;
+            case 'email_verification':
+                if (!params.email_id || !params.verification_token) {
+                    return { missing: 'email_id_or_verification_token' };
+                }
+                return null;
+            default:
+                return { missing: 'email_type' };
+        }
+    };
+    if (!params.email_type) {
+        return { missing: 'email_type' };
+    }
+    if (!params.email) {
+        return { missing: 'email' };
+    }
+    const typeValidation = validateForType();
+    if (typeValidation) {
+        return typeValidation;
+    }
+    const databaseInfo = await meta.request(GetDatabaseInfo, {
+        databaseId
+    });
+    const site = databaseInfo?.database?.sites?.nodes?.[0];
+    if (!site) {
+        throw new Error('Site not found for database');
+    }
+    const legalTermsModule = site.siteModules?.nodes?.[0];
+    const domainNode = site.domains?.nodes?.[0];
+    const theme = site.siteThemes?.nodes?.[0]?.theme;
+    if (!legalTermsModule || !domainNode || !theme) {
+        throw new Error('Missing site configuration for email');
+    }
+    const subdomain = domainNode.subdomain;
+    const domain = domainNode.domain;
+    const supportEmail = legalTermsModule.data.emails.support;
+    const logo = site.logo?.url;
+    const company = legalTermsModule.data.company;
+    const website = company.website;
+    const nick = company.nick;
+    const name = company.name;
+    const primary = theme.primary;
+    const hostname = subdomain ? [subdomain, domain].join('.') : domain;
+    // Treat localhost-style hosts specially so we can generate
+    // http://localhost[:port]/... links for local dev without
+    // breaking production URLs.
+    const isLocalHost = hostname.startsWith('localhost') ||
+        hostname.startsWith('0.0.0.0') ||
+        hostname.endsWith('.localhost');
+    // Optional: LOCAL_APP_PORT lets you attach a port for local dashboards
+    // e.g. LOCAL_APP_PORT=3000 -> http://localhost:3000
+    // It is ignored for non-local hostnames. Only allow on DRY RUNs
+    const localPort = isLocalHost && isDryRun && process.env.LOCAL_APP_PORT
+        ? `:${process.env.LOCAL_APP_PORT}`
+        : '';
+    // Use http only for local dry-run to avoid browser TLS warnings
+    // in dev; production stays https.
+    const protocol = isLocalHost && isDryRun ? 'http' : 'https';
+    const url = new URL(`${protocol}://${hostname}${localPort}`);
+    let subject;
+    let subMessage;
+    let linkText;
+    let inviterName;
+    switch (params.email_type) {
+        case 'invite_email': {
+            if (!params.invite_token || !params.sender_id) {
+                return { missing: 'invite_token_or_sender_id' };
+            }
+            url.pathname = 'register';
+            url.searchParams.append('invite_token', params.invite_token);
+            url.searchParams.append('email', params.email);
+            const scope = Number(params.invite_type) === 2 ? 'org' : 'app';
+            url.searchParams.append('type', scope);
+            const inviter = await client.request(GetUser, {
+                userId: params.sender_id
+            });
+            inviterName = inviter?.user?.displayName;
+            if (inviterName) {
+                subject = `${inviterName} invited you to ${nick}!`;
+                subMessage = `You've been invited to ${nick}`;
+            }
+            else {
+                subject = `Welcome to ${nick}!`;
+                subMessage = `You've been invited to ${nick}`;
+            }
+            linkText = 'Join Us';
+            break;
+        }
+        case 'forgot_password': {
+            if (!params.user_id || !params.reset_token) {
+                return { missing: 'user_id_or_reset_token' };
+            }
+            url.pathname = 'reset-password';
+            url.searchParams.append('role_id', params.user_id);
+            url.searchParams.append('reset_token', params.reset_token);
+            subject = `${nick} Password Reset Request`;
+            subMessage = 'Click below to reset your password';
+            linkText = 'Reset Password';
+            break;
+        }
+        case 'email_verification': {
+            if (!params.email_id || !params.verification_token) {
+                return { missing: 'email_id_or_verification_token' };
+            }
+            url.pathname = 'verify-email';
+            url.searchParams.append('email_id', params.email_id);
+            url.searchParams.append('verification_token', params.verification_token);
+            subject = `${nick} Email Verification`;
+            subMessage = 'Please confirm your email address';
+            linkText = 'Confirm Email';
+            break;
+        }
+        default:
+            return false;
+    }
+    const link = url.href;
+    const html = (0, mjml_1.generate)({
+        title: subject,
+        link,
+        linkText,
+        message: subject,
+        subMessage,
+        bodyBgColor: 'white',
+        headerBgColor: 'white',
+        messageBgColor: 'white',
+        messageTextColor: '#414141',
+        messageButtonBgColor: primary,
+        messageButtonTextColor: 'white',
+        companyName: name,
+        supportEmail,
+        website,
+        logo,
+        headerImageProps: {
+            alt: 'logo',
+            align: 'center',
+            border: 'none',
+            width: '162px',
+            paddingLeft: '0px',
+            paddingRight: '0px',
+            paddingBottom: '0px',
+            paddingTop: '0'
+        }
+    });
+    if (isDryRun) {
+        logger.info('DRY RUN email (skipping send)', {
+            email_type: params.email_type,
+            email: params.email,
+            subject,
+            link
+        });
+    }
+    else {
+        const sendEmail = useSmtp ? simple_smtp_server_1.send : postmaster_1.send;
+        await sendEmail({
+            to: params.email,
+            subject,
+            html
+        });
+    }
+    return {
+        complete: true,
+        ...(isDryRun ? { dryRun: true } : null)
+    };
+};
+exports.sendEmailLink = sendEmailLink;
+// HTTP/Knative entrypoint (used by @constructive-io/knative-job-fn wrapper)
+app.post('/', async (req, res, next) => {
+    try {
+        const params = (req.body || {});
+        const databaseId = req.get('X-Database-Id') || req.get('x-database-id') || process.env.DEFAULT_DATABASE_ID;
+        if (!databaseId) {
+            return res.status(400).json({ error: 'Missing X-Database-Id header or DEFAULT_DATABASE_ID' });
+        }
+        const graphqlUrl = getRequiredEnv('GRAPHQL_URL');
+        const metaGraphqlUrl = process.env.META_GRAPHQL_URL || graphqlUrl;
+        const client = createGraphQLClient(graphqlUrl, 'GRAPHQL_HOST_HEADER');
+        const meta = createGraphQLClient(metaGraphqlUrl, 'META_GRAPHQL_HOST_HEADER');
+        const result = await (0, exports.sendEmailLink)(params, {
+            client,
+            meta,
+            databaseId
+        });
+        res.status(200).json(result);
+    }
+    catch (err) {
+        next(err);
+    }
+});
+exports.default = app;
+// When executed directly (e.g. via `node dist/index.js`), start an HTTP server.
+if (require.main === module) {
+    const port = Number(process.env.PORT ?? 8080);
+    // @constructive-io/knative-job-fn exposes a .listen method that delegates to the Express app
+    app.listen(port, () => {
+        logger.info(`listening on port ${port}`);
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@constructive-io/send-email-link-fn",
+  "version": "0.3.1",
+  "description": "Knative function to send email links (invite, password reset, email verification) using Constructive jobs",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "directories": {
+    "lib": "src",
+    "test": "__tests__"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev"
+  },
+  "devDependencies": {
+    "makage": "^0.1.10"
+  },
+  "dependencies": {
+    "@constructive-io/knative-job-fn": "^0.3.1",
+    "@launchql/mjml": "0.1.1",
+    "@launchql/postmaster": "0.1.4",
+    "@launchql/styled-email": "0.1.0",
+    "@pgpmjs/env": "^2.10.0",
+    "@pgpmjs/logger": "^1.4.0",
+    "graphql-request": "^7.1.2",
+    "graphql-tag": "^2.12.6",
+    "simple-smtp-server": "^0.2.0"
+  },
+  "gitHead": "3ffd5718e86ea5fa9ca6e0930aeb510cf392f343"
+}