@locusgraph/email 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LocusGraph
+
+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

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @locusgraph/email
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+LocusGraph transactional emails as React templates. Square panel, hairline borders and a pill button, with colors from `@locusgraph/tokens`. Everything is inline-styled tables, so it renders in Gmail, Outlook and Apple Mail. No React Email dependency.
+
+```bash
+pnpm add @locusgraph/email react react-dom
+```
+
+```ts
+import { invitationEmail } from "@locusgraph/email";
+
+const { subject, html, text } = invitationEmail({
+  organizationName: "Acme Inc",
+  inviterName: "Dana Rivera",
+  role: "member",
+  acceptUrl,
+  expiresOn: "Oct 24, 2026",
+});
+```
+
+| Function | Sends |
+|---|---|
+| `invitationEmail` | Invitation to join an organization |
+| `receiptEmail` | A payment receipt, amount in cents |
+| `lowCreditsEmail` | Low or empty wallet, balance in micro-USD |
+| `usageOverPlanEmail` | Quotas over the plan |
+
+Each returns `{ subject, html, text }`; pass all three to your mail provider. Build new templates from `EmailLayout`, `EmailLabel`, `EmailHeading`, `EmailText`, `EmailButton` and `EmailRows`, then `renderEmail(subject, element)`.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { EmailLayout } from "./kit/email-layout.js";
+export { EmailButton, EmailHeading, EmailLabel, EmailRows, EmailText } from "./kit/parts.js";
+export { type RenderedEmail, renderEmail } from "./render.js";
+export * from "./templates/invitation.js";
+export * from "./templates/low-credits.js";
+export * from "./templates/receipt.js";
+export * from "./templates/usage-over-plan.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { EmailLayout } from "./kit/email-layout.js";
+export { EmailButton, EmailHeading, EmailLabel, EmailRows, EmailText } from "./kit/parts.js";
+export { renderEmail } from "./render.js";
+export * from "./templates/invitation.js";
+export * from "./templates/low-credits.js";
+export * from "./templates/receipt.js";
+export * from "./templates/usage-over-plan.js";

package/dist/kit/email-layout.d.ts

@@ -0,0 +1,8 @@
+import type * as React from "react";
+type EmailLayoutProps = {
+    preview: string;
+    children: React.ReactNode;
+    footer?: React.ReactNode;
+};
+export declare function EmailLayout({ preview, children, footer }: EmailLayoutProps): React.JSX.Element;
+export {};

package/dist/kit/email-layout.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { contentWidth, emailColors, emailFonts } from "./theme.js";
+export function EmailLayout({ preview, children, footer }) {
+    return (_jsxs("html", { lang: "en", children: [_jsxs("head", { children: [_jsx("meta", { httpEquiv: "Content-Type", content: "text/html; charset=UTF-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("meta", { name: "color-scheme", content: "light" })] }), _jsxs("body", { style: {
+                    margin: 0,
+                    padding: 0,
+                    backgroundColor: emailColors.page,
+                    fontFamily: emailFonts.sans,
+                }, children: [_jsx("div", { style: { display: "none", maxHeight: 0, overflow: "hidden" }, children: preview }), _jsx("table", { role: "presentation", width: "100%", cellPadding: 0, cellSpacing: 0, style: { backgroundColor: emailColors.page }, children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { align: "center", style: { padding: "40px 16px" }, children: _jsx("table", { role: "presentation", width: contentWidth, cellPadding: 0, cellSpacing: 0, style: { maxWidth: contentWidth, width: "100%" }, children: _jsxs("tbody", { children: [_jsx("tr", { children: _jsxs("td", { style: { paddingBottom: 16, fontSize: 16, color: emailColors.foreground }, children: [_jsx("strong", { children: "locus" }), _jsx("span", { style: { fontWeight: 300 }, children: "graph" })] }) }), _jsx("tr", { children: _jsx("td", { style: {
+                                                            backgroundColor: emailColors.surface,
+                                                            border: `1px solid ${emailColors.line}`,
+                                                            padding: 32,
+                                                            color: emailColors.foreground,
+                                                        }, children: children }) }), footer && (_jsx("tr", { children: _jsx("td", { style: {
+                                                            paddingTop: 16,
+                                                            fontSize: 12,
+                                                            lineHeight: "18px",
+                                                            color: emailColors.muted,
+                                                        }, children: footer }) }))] }) }) }) }) }) })] })] }));
+}

package/dist/kit/parts.d.ts

@@ -0,0 +1,18 @@
+import type * as React from "react";
+export declare function EmailLabel({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function EmailHeading({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function EmailText({ children, muted, }: {
+    children: React.ReactNode;
+    muted?: boolean;
+}): React.JSX.Element;
+export declare function EmailButton({ href, children }: {
+    href: string;
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function EmailRows({ rows }: {
+    rows: [label: string, value: string][];
+}): React.JSX.Element;

package/dist/kit/parts.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { emailColors, emailFonts } from "./theme.js";
+export function EmailLabel({ children }) {
+    return (_jsx("p", { style: {
+            margin: "0 0 8px",
+            fontFamily: emailFonts.mono,
+            fontSize: 12,
+            color: emailColors.muted,
+        }, children: children }));
+}
+export function EmailHeading({ children }) {
+    return (_jsx("h1", { style: {
+            margin: "0 0 12px",
+            fontSize: 22,
+            lineHeight: "28px",
+            fontWeight: 600,
+            letterSpacing: "-0.02em",
+        }, children: children }));
+}
+export function EmailText({ children, muted = false, }) {
+    return (_jsx("p", { style: {
+            margin: "0 0 16px",
+            fontSize: 15,
+            lineHeight: "24px",
+            color: muted ? emailColors.muted : emailColors.foreground,
+        }, children: children }));
+}
+export function EmailButton({ href, children }) {
+    return (_jsx("table", { role: "presentation", cellPadding: 0, cellSpacing: 0, style: { margin: "8px 0 16px" }, children: _jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { style: { backgroundColor: emailColors.btn, borderRadius: 9999 }, children: _jsx("a", { href: href, style: {
+                            display: "inline-block",
+                            padding: "10px 20px",
+                            fontSize: 14,
+                            fontWeight: 600,
+                            color: emailColors.btnInk,
+                            textDecoration: "none",
+                        }, children: children }) }) }) }) }));
+}
+export function EmailRows({ rows }) {
+    return (_jsx("table", { role: "presentation", width: "100%", cellPadding: 0, cellSpacing: 0, style: { margin: "8px 0 16px", borderTop: `1px solid ${emailColors.line}` }, children: _jsx("tbody", { children: rows.map(([label, value]) => (_jsxs("tr", { children: [_jsx("td", { style: {
+                            padding: "10px 0",
+                            fontSize: 14,
+                            color: emailColors.muted,
+                            borderBottom: `1px solid ${emailColors.line}`,
+                        }, children: label }), _jsx("td", { align: "right", style: {
+                            padding: "10px 0",
+                            fontSize: 14,
+                            borderBottom: `1px solid ${emailColors.line}`,
+                        }, children: value })] }, label))) }) }));
+}

package/dist/kit/theme.d.ts

@@ -0,0 +1,21 @@
+export declare const emailColors: {
+    page: string;
+    line: string;
+    bad: string;
+    brandGlow: string;
+    btn: string;
+    btnInk: string;
+    faint: string;
+    foreground: string;
+    ghost: string;
+    good: string;
+    info: string;
+    muted: string;
+    surface: string;
+    warn: string;
+};
+export declare const emailFonts: {
+    sans: "Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif";
+    mono: "'Fira Code', SFMono-Regular, Menlo, Consolas, monospace";
+};
+export declare const contentWidth = 560;

package/dist/kit/theme.js

@@ -0,0 +1,8 @@
+import { fonts, hairline, lightColors } from "@locusgraph/tokens";
+export const emailColors = {
+    ...lightColors,
+    page: "#f4f4f5",
+    line: hairline(lightColors),
+};
+export const emailFonts = { sans: fonts.emailSafeSans, mono: fonts.emailSafeMono };
+export const contentWidth = 560;

package/dist/render.d.ts

@@ -0,0 +1,7 @@
+import type * as React from "react";
+export type RenderedEmail = {
+    subject: string;
+    html: string;
+    text: string;
+};
+export declare function renderEmail(subject: string, email: React.ReactElement): RenderedEmail;

package/dist/render.js

@@ -0,0 +1,19 @@
+import { renderToStaticMarkup } from "react-dom/server";
+function plainText(html) {
+    return html
+        .replace(/<div style="display:none[^>]*>[\s\S]*?<\/div>/, "")
+        .replace(/<a [^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g, "$2: $1")
+        .replace(/<\/(p|h1|tr|table)>/g, "\n")
+        .replace(/<\/td>/g, " ")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&amp;/g, "&")
+        .replace(/&#x27;|&#39;/g, "'")
+        .replace(/&quot;/g, '"')
+        .replace(/[ \t]+/g, " ")
+        .replace(/\n\s*\n+/g, "\n\n")
+        .trim();
+}
+export function renderEmail(subject, email) {
+    const html = `<!DOCTYPE html>${renderToStaticMarkup(email)}`;
+    return { subject, html, text: plainText(html) };
+}

package/dist/templates/invitation.d.ts

@@ -0,0 +1,9 @@
+export type InvitationEmailProps = {
+    organizationName: string;
+    inviterName: string;
+    role: string;
+    acceptUrl: string;
+    expiresOn: string;
+};
+export declare function InvitationEmail({ organizationName, inviterName, role, acceptUrl, expiresOn, }: InvitationEmailProps): import("react").JSX.Element;
+export declare function invitationEmail(props: InvitationEmailProps): import("..").RenderedEmail;

package/dist/templates/invitation.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { EmailLayout } from "../kit/email-layout.js";
+import { EmailButton, EmailHeading, EmailLabel, EmailText } from "../kit/parts.js";
+import { renderEmail } from "../render.js";
+export function InvitationEmail({ organizationName, inviterName, role, acceptUrl, expiresOn, }) {
+    return (_jsxs(EmailLayout, { preview: `${inviterName} invited you to ${organizationName}`, footer: `The invitation expires on ${expiresOn}. If you did not expect it, ignore this email.`, children: [_jsx(EmailLabel, { children: "Invitation" }), _jsxs(EmailHeading, { children: ["Join ", organizationName, " on LocusGraph"] }), _jsxs(EmailText, { children: [inviterName, " invited you to ", organizationName, " as ", role, ". Sign in with Google or GitHub to accept."] }), _jsx(EmailButton, { href: acceptUrl, children: "Accept invitation" })] }));
+}
+export function invitationEmail(props) {
+    return renderEmail(`Join ${props.organizationName} on LocusGraph`, _jsx(InvitationEmail, { ...props }));
+}

package/dist/templates/low-credits.d.ts

@@ -0,0 +1,7 @@
+export type LowCreditsEmailProps = {
+    organizationName: string;
+    balanceMicroUsd: number;
+    buyCreditsUrl: string;
+};
+export declare function LowCreditsEmail({ organizationName, balanceMicroUsd, buyCreditsUrl, }: LowCreditsEmailProps): import("react").JSX.Element;
+export declare function lowCreditsEmail(props: LowCreditsEmailProps): import("..").RenderedEmail;

package/dist/templates/low-credits.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatMicroUsd } from "@locusgraph/utils";
+import { EmailLayout } from "../kit/email-layout.js";
+import { EmailButton, EmailHeading, EmailLabel, EmailText } from "../kit/parts.js";
+import { renderEmail } from "../render.js";
+export function LowCreditsEmail({ organizationName, balanceMicroUsd, buyCreditsUrl, }) {
+    const empty = balanceMicroUsd <= 0;
+    return (_jsxs(EmailLayout, { preview: empty ? `${organizationName} is out of credits` : `${organizationName} is low on credits`, children: [_jsx(EmailLabel, { children: "Credits" }), _jsx(EmailHeading, { children: empty ? "Out of credits" : `${formatMicroUsd(balanceMicroUsd)} of credits left` }), _jsx(EmailText, { children: empty
+                    ? `Paid usage for ${organizationName} is paused until you add credits.`
+                    : `Add credits so paid usage for ${organizationName} does not stop.` }), _jsx(EmailButton, { href: buyCreditsUrl, children: "Buy credits" })] }));
+}
+export function lowCreditsEmail(props) {
+    const subject = props.balanceMicroUsd <= 0 ? "You are out of credits" : "Your credits are running low";
+    return renderEmail(`${subject} on ${props.organizationName}`, _jsx(LowCreditsEmail, { ...props }));
+}

package/dist/templates/receipt.d.ts

@@ -0,0 +1,9 @@
+export type ReceiptEmailProps = {
+    organizationName: string;
+    description: string;
+    amountCents: number;
+    paidOn: string;
+    receiptUrl: string;
+};
+export declare function ReceiptEmail({ organizationName, description, amountCents, paidOn, receiptUrl, }: ReceiptEmailProps): import("react").JSX.Element;
+export declare function receiptEmail(props: ReceiptEmailProps): import("..").RenderedEmail;

package/dist/templates/receipt.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatCents } from "@locusgraph/utils";
+import { EmailLayout } from "../kit/email-layout.js";
+import { EmailButton, EmailHeading, EmailLabel, EmailRows, EmailText } from "../kit/parts.js";
+import { renderEmail } from "../render.js";
+export function ReceiptEmail({ organizationName, description, amountCents, paidOn, receiptUrl, }) {
+    return (_jsxs(EmailLayout, { preview: `${formatCents(amountCents)} paid for ${organizationName}`, footer: "Stripe processed this payment. The receipt link shows the full invoice.", children: [_jsx(EmailLabel, { children: "Receipt" }), _jsxs(EmailHeading, { children: [formatCents(amountCents), " paid"] }), _jsxs(EmailText, { children: ["Thanks. Here is what ", organizationName, " paid for."] }), _jsx(EmailRows, { rows: [
+                    ["Item", description],
+                    ["Date", paidOn],
+                    ["Total", formatCents(amountCents)],
+                ] }), _jsx(EmailButton, { href: receiptUrl, children: "View receipt" })] }));
+}
+export function receiptEmail(props) {
+    return renderEmail(`Receipt: ${formatCents(props.amountCents)} for ${props.organizationName}`, _jsx(ReceiptEmail, { ...props }));
+}

package/dist/templates/usage-over-plan.d.ts

@@ -0,0 +1,13 @@
+export type OverQuota = {
+    key: string;
+    used: number;
+    included: number;
+    periodLabel: string;
+};
+export type UsageOverPlanEmailProps = {
+    organizationName: string;
+    quotas: OverQuota[];
+    usageUrl: string;
+};
+export declare function UsageOverPlanEmail({ organizationName, quotas, usageUrl, }: UsageOverPlanEmailProps): import("react").JSX.Element;
+export declare function usageOverPlanEmail(props: UsageOverPlanEmailProps): import("..").RenderedEmail;

package/dist/templates/usage-over-plan.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatCount } from "@locusgraph/utils";
+import { EmailLayout } from "../kit/email-layout.js";
+import { EmailButton, EmailHeading, EmailLabel, EmailRows, EmailText } from "../kit/parts.js";
+import { renderEmail } from "../render.js";
+export function UsageOverPlanEmail({ organizationName, quotas, usageUrl, }) {
+    return (_jsxs(EmailLayout, { preview: `${organizationName} is over its plan`, children: [_jsx(EmailLabel, { children: "Usage" }), _jsx(EmailHeading, { children: "Usage is over your plan" }), _jsxs(EmailText, { children: [organizationName, " used more than its plan includes. Usage past the plan comes from prepaid credits, or stops when overage is off."] }), _jsx(EmailRows, { rows: quotas.map((quota) => [
+                    quota.key,
+                    `${formatCount(quota.used)} of ${formatCount(quota.included)} ${quota.periodLabel}`,
+                ]) }), _jsx(EmailButton, { href: usageUrl, children: "See usage" })] }));
+}
+export function usageOverPlanEmail(props) {
+    return renderEmail(`${props.organizationName} is over its plan`, _jsx(UsageOverPlanEmail, { ...props }));
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@locusgraph/email",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "LocusGraph transactional emails as React templates with inline styles: invitation, receipt, low credits and usage over plan.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/locusgraph/design.git",
+    "directory": "packages/email"
+  },
+  "homepage": "https://design.locusgraph.com",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "dependencies": {
+    "@locusgraph/tokens": "0.1.1",
+    "@locusgraph/utils": "0.1.1"
+  },
+  "devDependencies": {
+    "@locusgraph/config": "0.1.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/esm-extensions.mjs dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }