@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/diagnostics.js

@@ -0,0 +1,106 @@
+import { Schema } from "effect";
+export const DIAGNOSTIC_CODES = [
+    "invalid-source",
+    "missing-column",
+    "invalid-column",
+    "invalid-scope",
+    "invalid-scope-path",
+    "scope-reads-all",
+    "scope-unused",
+    "scope-member-overlap",
+    "source-with-actions",
+    "source-with-index",
+    "invalid-metric",
+    "unknown-metric",
+    "circular-metric",
+    "invalid-join",
+    "missing-join",
+    "invalid-entity",
+    "invalid-property",
+    "invalid-relationship",
+    "invalid-actions",
+    "invalid-action",
+    "invalid-action-input",
+    "invalid-role",
+    "invalid-name",
+    "reserved-name",
+    "duplicate-name",
+    "invalid-entity-id",
+    "duplicate-entity-id",
+    "missing-label",
+    "missing-description",
+    "invalid-title",
+    "invalid-options",
+    "invalid-default",
+    "invalid-constraint",
+    "unknown-relationship-target",
+    "inverse-collision",
+    "invalid-on-delete",
+    "invalid-phrase",
+    "invalid-index",
+    "unknown-reference",
+    "invalid-renamed-from",
+    "earlier-name",
+    "invalid-guide",
+    "invalid-writes",
+    "generated-update-empty",
+    "managed-without-effect",
+    "missing-permissions",
+    "invalid-permission",
+    "unknown-permission",
+    "removed-allow",
+    "unreachable-action",
+    "wildcard-permission",
+    "invalid-sign-in",
+    "invalid-connection",
+    "invalid-feedback",
+    "invalid-discovery",
+    "invalid-email",
+    "feedback-unanswerable",
+    "unknown-connection",
+    "unused-connection",
+    "invalid-prepare",
+    "invalid-tool-name",
+    "invalid-alignment",
+    "single-entity-model-metric",
+    "invalid-workflow",
+    "workflow_role_unknown",
+    "workflow_role_is_member",
+    "workflow_role_grants_nothing",
+    "workflow_role_wildcard",
+    "workflow_role_scoped",
+    "workflow_cron_never_fires",
+    "workflow_input_invalid",
+    "workflow_cron_invalid",
+    "workflow_run_missing",
+    "invalid-trigger",
+    "trigger_action_unknown",
+    "trigger_function_async",
+    "workflow_trigger_limit_exceeded",
+    "workflow_webhook_duplicate",
+    "workflow_webhook_input_invalid",
+    "workflow_webhook_mixed_triggers",
+    "workflow_webhook_signature_invalid",
+    "workflow_webhook_verification_invalid",
+    "workflow_webhook_headers_invalid",
+    "workflow_webhook_limit_exceeded",
+];
+/** A problem `check` found in an ontology definition. */
+export const Diagnostic = Schema.Struct({
+    severity: Schema.Literals(["error", "warning", "info"]),
+    code: Schema.Literals(DIAGNOSTIC_CODES),
+    /** Where the problem is, for example `lead.properties.status.options[1]`. */
+    path: Schema.String,
+    message: Schema.String,
+});
+/** `defineOntology` found errors. Every diagnostic, including warnings, is attached. */
+export class InvalidOntology extends Schema.TaggedError()("InvalidOntology", {
+    message: Schema.String,
+    diagnostics: Schema.Array(Diagnostic),
+}) {
+}
+export function formatDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => `${diagnostic.severity} ${diagnostic.path}: ${diagnostic.message} [${diagnostic.code}]`)
+        .join("\n");
+}

package/dist/emails.d.ts

@@ -0,0 +1,70 @@
+import type { Diagnostic } from "./diagnostics.js";
+/**
+ * An email the workspace writes and the platform sends with a sign-in link, named by
+ * `User.sendSignInLink`. Every field is plain text, in which `{{name}}` stands for a value the
+ * action passes, and `{{member.name}}`, `{{member.firstName}}` and `{{workspace.name}}` for the
+ * recipient and the workspace. The platform lays the fields out, escapes them and adds the
+ * plain-text part; `action` labels the one button, which signs the person in and opens the path
+ * the action names. A field whose text is empty once filled in is left out.
+ */
+export interface EmailTemplate {
+    readonly subject: string;
+    /** A short line above the heading, such as "Review requested". */
+    readonly eyebrow?: string;
+    readonly heading: string;
+    /** A box naming what the email is about: a title, and a line below it. */
+    readonly card?: {
+        readonly title: string;
+        readonly detail?: string;
+    };
+    /** A quoted message, such as the sender's own note. */
+    readonly note?: string;
+    readonly paragraphs?: ReadonlyArray<string>;
+    /** The button's label. */
+    readonly action: string;
+    /** Small print at the bottom, such as why the person received the email. */
+    readonly footer?: string;
+    /**
+     * The address replies go to, such as `legal@example.com`. Without it, replies go to the member
+     * whose action sent the email, if a member did. The email is always sent from the platform's
+     * address under the workspace's name.
+     */
+    readonly replyTo?: string;
+}
+/** The values every email may use besides those the action passes. */
+export declare const BUILT_IN_EMAIL_VALUES: readonly ["member.name", "member.firstName", "workspace.name"];
+/**
+ * The query parameter of the callback a sign-in link is requested with, naming the queued email it
+ * delivers. The platform reads it from Neon Auth's link and leaves it out of the path the person
+ * lands on.
+ */
+export declare const SIGN_IN_EMAIL_PARAMETER = "sign_in_email";
+/** The most emails an ontology declares. */
+export declare const MAX_EMAILS = 50;
+/** The longest subject, in characters. */
+export declare const MAX_EMAIL_SUBJECT = 200;
+/** The longest other field, and the longest value an action passes, in characters. */
+export declare const MAX_EMAIL_TEXT = 2000;
+/** The most paragraphs of one email. */
+export declare const MAX_EMAIL_PARAGRAPHS = 20;
+/** The most values one email takes. */
+export declare const MAX_EMAIL_VALUES = 50;
+/** The longest path a sign-in link returns to. */
+export declare const MAX_RETURN_PATH = 1024;
+type Report = (code: Diagnostic["code"], path: string, message: string, severity?: Diagnostic["severity"]) => void;
+/** The values an action must pass for this email: its placeholders that are not built in. */
+export declare function emailValueNames(template: EmailTemplate): ReadonlyArray<string>;
+/** The text with each placeholder replaced by its value; a value it does not have is empty. */
+export declare function fillEmailText(text: string, values: Readonly<Record<string, string>>): string;
+/**
+ * The path a sign-in link may return to: a path of the app, with its query, at most
+ * {@link MAX_RETURN_PATH} characters. Anything else, such as another origin, is undefined.
+ */
+export declare function appReturnPath(value: string): string | undefined;
+/**
+ * The declared emails by wire name, each checked: its fields, their lengths and their
+ * placeholders. `wireName` turns a camelCase name into its wire form, reporting one that cannot
+ * round-trip.
+ */
+export declare function emailOptions(value: unknown, report: Report, wireName: (name: string, path: string) => string | undefined): Readonly<Record<string, EmailTemplate>>;
+export {};

package/dist/emails.js

@@ -0,0 +1,221 @@
+import { isRecord } from "./authoring-names.js";
+/** The values every email may use besides those the action passes. */
+export const BUILT_IN_EMAIL_VALUES = ["member.name", "member.firstName", "workspace.name"];
+/**
+ * The query parameter of the callback a sign-in link is requested with, naming the queued email it
+ * delivers. The platform reads it from Neon Auth's link and leaves it out of the path the person
+ * lands on.
+ */
+export const SIGN_IN_EMAIL_PARAMETER = "sign_in_email";
+/** The most emails an ontology declares. */
+export const MAX_EMAILS = 50;
+/** The longest subject, in characters. */
+export const MAX_EMAIL_SUBJECT = 200;
+/** The longest other field, and the longest value an action passes, in characters. */
+export const MAX_EMAIL_TEXT = 2000;
+/** The most paragraphs of one email. */
+export const MAX_EMAIL_PARAGRAPHS = 20;
+/** The most values one email takes. */
+export const MAX_EMAIL_VALUES = 50;
+/** The longest path a sign-in link returns to. */
+export const MAX_RETURN_PATH = 1024;
+const FIELDS = [
+    "subject",
+    "eyebrow",
+    "heading",
+    "card",
+    "note",
+    "paragraphs",
+    "action",
+    "footer",
+    "replyTo",
+];
+const REQUIRED = ["subject", "heading", "action"];
+const OPTIONAL_TEXT = ["eyebrow", "note", "footer"];
+const PLACEHOLDER = /\{\{\s*([^{}]*?)\s*\}\}/g;
+const VALUE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const EMAIL_ADDRESS = /^[^\s@<>",;]+@[^\s@<>",;.]+(?:\.[^\s@<>",;.]+)+$/;
+function isBuiltIn(name) {
+    return BUILT_IN_EMAIL_VALUES.includes(name);
+}
+/** Every text of an email, with the path of its field. */
+function emailTexts(template) {
+    return [
+        ["subject", template.subject],
+        ...(template.eyebrow === undefined ? [] : [["eyebrow", template.eyebrow]]),
+        ["heading", template.heading],
+        ...(template.card === undefined ? [] : [["card.title", template.card.title]]),
+        ...(template.card?.detail === undefined
+            ? []
+            : [["card.detail", template.card.detail]]),
+        ...(template.note === undefined ? [] : [["note", template.note]]),
+        ...(template.paragraphs ?? []).map((text, index) => [`paragraphs.${index}`, text]),
+        ["action", template.action],
+        ...(template.footer === undefined ? [] : [["footer", template.footer]]),
+    ];
+}
+/** The placeholders of one text, in order. */
+function placeholders(text) {
+    return [...text.matchAll(PLACEHOLDER)].map((match) => match[1]);
+}
+/** The values an action must pass for this email: its placeholders that are not built in. */
+export function emailValueNames(template) {
+    const names = new Set();
+    for (const [, text] of emailTexts(template)) {
+        for (const name of placeholders(text)) {
+            if (!isBuiltIn(name)) {
+                names.add(name);
+            }
+        }
+    }
+    return [...names];
+}
+/** The text with each placeholder replaced by its value; a value it does not have is empty. */
+export function fillEmailText(text, values) {
+    return text.replace(PLACEHOLDER, (_, name) => Object.hasOwn(values, name) ? values[name] : "");
+}
+/**
+ * The path a sign-in link may return to: a path of the app, with its query, at most
+ * {@link MAX_RETURN_PATH} characters. Anything else, such as another origin, is undefined.
+ */
+export function appReturnPath(value) {
+    if (value.length > MAX_RETURN_PATH ||
+        !value.startsWith("/") ||
+        value.startsWith("//") ||
+        value.startsWith("/\\") ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        return undefined;
+    }
+    const url = URL.parse(value, "https://return-path.invalid");
+    return url?.origin === "https://return-path.invalid"
+        ? `${url.pathname}${url.search}${url.hash}`
+        : undefined;
+}
+function checkText(text, path, limit, report) {
+    if (typeof text !== "string" || text.trim() === "") {
+        report("invalid-email", path, `${path} is a text.`);
+        return false;
+    }
+    if (text.length > limit) {
+        report("invalid-email", path, `${path} has at most ${limit} characters.`);
+        return false;
+    }
+    const rest = text.replace(PLACEHOLDER, "");
+    if (rest.includes("{{") || rest.includes("}}")) {
+        report("invalid-email", path, "Write {{ and }} only around a value, as in {{agreement}}.");
+        return false;
+    }
+    let valid = true;
+    for (const name of placeholders(text)) {
+        if (!isBuiltIn(name) && !VALUE_NAME.test(name)) {
+            report("invalid-email", path, `{{${name}}} is not a value: use a name the action passes, such as {{agreement}}, or ` +
+                `${BUILT_IN_EMAIL_VALUES.map((value) => `{{${value}}}`).join(", ")}.`);
+            valid = false;
+        }
+    }
+    return valid;
+}
+function emailTemplate(value, path, report) {
+    if (!isRecord(value)) {
+        report("invalid-email", path, "An email is { subject, heading, action, … } in plain text.");
+        return undefined;
+    }
+    let valid = true;
+    for (const key of Object.keys(value)) {
+        if (!FIELDS.includes(key)) {
+            report("invalid-email", `${path}.${key}`, `Unknown email field ${key}; an email has ${FIELDS.join(", ")}.`);
+            valid = false;
+        }
+    }
+    for (const key of REQUIRED) {
+        const limit = key === "subject" ? MAX_EMAIL_SUBJECT : MAX_EMAIL_TEXT;
+        valid = checkText(value[key], `${path}.${key}`, limit, report) && valid;
+    }
+    for (const key of OPTIONAL_TEXT) {
+        if (value[key] !== undefined) {
+            valid = checkText(value[key], `${path}.${key}`, MAX_EMAIL_TEXT, report) && valid;
+        }
+    }
+    if (value.card !== undefined) {
+        const card = value.card;
+        if (!isRecord(card) || Object.keys(card).some((key) => key !== "title" && key !== "detail")) {
+            report("invalid-email", `${path}.card`, "card is { title, detail }.");
+            valid = false;
+        }
+        else {
+            valid = checkText(card.title, `${path}.card.title`, MAX_EMAIL_TEXT, report) && valid;
+            if (card.detail !== undefined) {
+                valid = checkText(card.detail, `${path}.card.detail`, MAX_EMAIL_TEXT, report) && valid;
+            }
+        }
+    }
+    if (value.replyTo !== undefined &&
+        (typeof value.replyTo !== "string" ||
+            value.replyTo.length > 254 ||
+            !EMAIL_ADDRESS.test(value.replyTo))) {
+        report("invalid-email", `${path}.replyTo`, "replyTo is one email address, such as legal@example.com, without a name.");
+        valid = false;
+    }
+    if (value.paragraphs !== undefined) {
+        if (!Array.isArray(value.paragraphs) || value.paragraphs.length > MAX_EMAIL_PARAGRAPHS) {
+            report("invalid-email", `${path}.paragraphs`, `paragraphs is a list of at most ${MAX_EMAIL_PARAGRAPHS} texts.`);
+            valid = false;
+        }
+        else {
+            value.paragraphs.forEach((text, index) => {
+                valid = checkText(text, `${path}.paragraphs.${index}`, MAX_EMAIL_TEXT, report) && valid;
+            });
+        }
+    }
+    if (!valid) {
+        return undefined;
+    }
+    const card = value.card;
+    return {
+        subject: value.subject,
+        ...(value.eyebrow === undefined ? {} : { eyebrow: value.eyebrow }),
+        heading: value.heading,
+        ...(card === undefined
+            ? {}
+            : {
+                card: {
+                    title: card.title,
+                    ...(card.detail === undefined ? {} : { detail: card.detail }),
+                },
+            }),
+        ...(value.note === undefined ? {} : { note: value.note }),
+        ...(value.paragraphs === undefined
+            ? {}
+            : { paragraphs: [...value.paragraphs] }),
+        action: value.action,
+        ...(value.footer === undefined ? {} : { footer: value.footer }),
+        ...(value.replyTo === undefined ? {} : { replyTo: value.replyTo }),
+    };
+}
+/**
+ * The declared emails by wire name, each checked: its fields, their lengths and their
+ * placeholders. `wireName` turns a camelCase name into its wire form, reporting one that cannot
+ * round-trip.
+ */
+export function emailOptions(value, report, wireName) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isRecord(value)) {
+        report("invalid-email", "emails", "emails maps each email's name to { subject, heading, … }.");
+        return {};
+    }
+    const names = Object.keys(value);
+    if (names.length > MAX_EMAILS) {
+        report("invalid-email", "emails", `An ontology declares at most ${MAX_EMAILS} emails.`);
+    }
+    const emails = {};
+    for (const name of names) {
+        const wire = wireName(name, `emails.${name}`);
+        const template = emailTemplate(value[name], `emails.${name}`, report);
+        if (wire !== undefined && template !== undefined) {
+            emails[wire] = template;
+        }
+    }
+    return emails;
+}