@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/telegram.js

@@ -0,0 +1,173 @@
+import { TelegramFormatConverter } from "@chat-adapter/telegram";
+import { Lexer, Tokenizer } from "marked";
+export const TELEGRAM_LINK_PREVIEWS = ["external", "none", "all"];
+const converter = new TelegramFormatConverter();
+const urlTokenizer = new Tokenizer({ gfm: true });
+const visibleUrlStart = new RegExp(String.raw `(?<![\p{L}\p{N}_@/.:+-])(?:https?:\/\/|(?:` +
+    String.raw `(?:[\p{L}\p{N}](?:[\p{L}\p{N}-]*[\p{L}\p{N}])?\.)+(?:[\p{L}]{2,}|xn--[a-z0-9]+(?:-[a-z0-9]+)*)|` +
+    String.raw `(?:\d{1,3}\.){3}\d{1,3})(?![\p{L}\p{N}-]))`, "giu");
+// Initialize the public tokenizer with the same GFM rules used by the agent renderer.
+new Lexer({ gfm: true, tokenizer: urlTokenizer });
+/** Normalize HTTP(S) origins only; credential-bearing and non-web destinations are ineligible. */
+export function httpOrigin(value) {
+    const url = URL.parse(value);
+    return url && ["http:", "https:"].includes(url.protocol) && !url.username && !url.password
+        ? url.origin
+        : undefined;
+}
+export function isHttpOrigin(value) {
+    if (typeof value !== "string" || value !== value.trim() || !httpOrigin(value)) {
+        return false;
+    }
+    const url = new URL(value);
+    return url.pathname === "/" && !url.search && !url.hash;
+}
+/** Also validates programmatic standalone service configuration. */
+export function validateTelegramPreviews(settings) {
+    if (!/^[a-z][a-z0-9_]{0,63}$/.test(settings.connection) ||
+        (settings.linkPreviews !== undefined &&
+            !TELEGRAM_LINK_PREVIEWS.includes(settings.linkPreviews)) ||
+        (settings.additionalOwnOrigins !== undefined &&
+            (!Array.isArray(settings.additionalOwnOrigins) ||
+                !settings.additionalOwnOrigins.every(isHttpOrigin)))) {
+        throw new Error("Invalid Telegram channel preview settings.");
+    }
+}
+/** Public, non-secret deployment metadata; no request headers or cross-tenant suffix matching. */
+export function telegramPreviewEnvironment(environment) {
+    const channels = environment.SEGMENTSTREAM_CHANNELS
+        ? JSON.parse(environment.SEGMENTSTREAM_CHANNELS)
+        : {};
+    if (!channels || typeof channels !== "object" || Array.isArray(channels)) {
+        throw new Error("Invalid SEGMENTSTREAM_CHANNELS.");
+    }
+    if (channels.telegram !== undefined) {
+        validateTelegramPreviews(channels.telegram);
+    }
+    const declared = environment.SEGMENTSTREAM_APP_ORIGINS
+        ? JSON.parse(environment.SEGMENTSTREAM_APP_ORIGINS)
+        : [];
+    if (!Array.isArray(declared) || !declared.every(isHttpOrigin)) {
+        throw new Error("Invalid SEGMENTSTREAM_APP_ORIGINS.");
+    }
+    const candidates = [
+        ...declared,
+        environment.SEGMENTSTREAM_AGENT_ONTOLOGY_URL,
+        ...["VERCEL_PROJECT_PRODUCTION_URL", "VERCEL_URL", "VERCEL_BRANCH_URL"].map((key) => environment[key] ? `https://${environment[key]}` : undefined),
+    ];
+    return {
+        ...(channels.telegram === undefined ? {} : { channels }),
+        appOrigins: [
+            ...new Set(candidates.flatMap((value) => (value ? [httpOrigin(value)] : []))),
+        ].filter((value) => value !== undefined),
+    };
+}
+/** Telegram also auto-links visible domains without an HTTP scheme. */
+function bareLinks(text) {
+    let end = 0;
+    return [...text.matchAll(visibleUrlStart)].flatMap((match) => {
+        if (match.index < end) {
+            return []; // A URL inside another URL's query/fragment is not a separate destination.
+        }
+        const source = text.slice(match.index);
+        const prefix = /^https?:\/\//iu.test(source) ? "" : "http://";
+        const token = urlTokenizer.url(prefix + source);
+        end = match.index + (token ? token.raw.length - prefix.length : 0);
+        return token && httpOrigin(token.href) ? [{ url: token.href, offset: match.index, end }] : [];
+    });
+}
+/** Parse source Markdown, never escaped Telegram MarkdownV2. AST offsets are UTF-16. */
+function markdownLinks(markdown, plain = false) {
+    const links = [];
+    const visit = (node, base = 0, depth = 0) => {
+        const offset = base + (node.position?.start.offset ?? 0);
+        if (node.type === "code" || node.type === "inlineCode") {
+            // A formatting fallback sends literal code text, so its URLs become eligible again.
+            if (plain && depth < 32) {
+                visit(converter.toAst(node.value), offset, depth + 1);
+            }
+            return;
+        }
+        if (!plain && node.type === "table") {
+            return; // The existing Telegram renderer renders tables as code.
+        }
+        if (node.type === "link" || node.type === "image") {
+            if (httpOrigin(node.url)) {
+                links.push({ url: node.url, offset });
+            }
+            return;
+        }
+        if (node.type === "text") {
+            links.push(...bareLinks(node.value).map((link) => ({ ...link, offset: offset + link.offset })));
+        }
+        if ("children" in node) {
+            for (const child of node.children) {
+                visit(child, base, depth);
+            }
+        }
+    };
+    visit(converter.toAst(markdown));
+    return links.sort((a, b) => a.offset - b.offset);
+}
+export function telegramMarkdownLinks(markdown) {
+    return markdownLinks(markdown).map((link) => link.url);
+}
+/** Visible URLs and hidden destinations, excluding formatted code and linked-label lookalikes. */
+export function telegramTextLinks(text, entities = []) {
+    const protectedEntities = entities.filter((entity) => ["code", "pre", "text_link", "url"].includes(entity.type));
+    // Literal fallbacks can expose URLs in Markdown labels, definitions or HTML. The URL
+    // tokenizer handles their punctuation without interpreting that text as Markdown.
+    const bare = bareLinks(text);
+    const parsed = markdownLinks(text, true).flatMap((link) => {
+        const offset = text.indexOf(link.url, link.offset);
+        // An embedded Markdown match belongs to the complete visible URL's query/fragment.
+        return offset < 0 || bare.some((visible) => offset > visible.offset && offset < visible.end)
+            ? []
+            : [{ ...link, offset }];
+    });
+    const visible = [...parsed, ...bare].filter((link) => !protectedEntities.some((entity) => link.offset >= entity.offset && link.offset < entity.offset + entity.length));
+    const hidden = entities.flatMap((entity) => {
+        if (entity.type === "url") {
+            const value = text.slice(entity.offset, entity.offset + entity.length);
+            const url = /\s/u.test(value)
+                ? null
+                : URL.parse(/^[a-z][a-z0-9+.-]*:\/\//iu.test(value) ? value : `http://${value}`);
+            return url && httpOrigin(url.href) ? [{ url: url.href, offset: entity.offset }] : [];
+        }
+        return entity.type === "text_link" && entity.url && httpOrigin(entity.url)
+            ? [{ url: entity.url, offset: entity.offset }]
+            : [];
+    });
+    const ordered = new Map();
+    for (const link of [...visible, ...hidden].sort((a, b) => a.offset - b.offset)) {
+        if (!ordered.has(link.offset)) {
+            ordered.set(link.offset, link.url);
+        }
+    }
+    return [...ordered.values()];
+}
+/** Explicit modern > explicit legacy > channel mode > external default. Never merge caller options. */
+export function telegramPreviewOptions(caller, links, context = {}) {
+    if (caller.link_preview_options !== undefined) {
+        return { link_preview_options: caller.link_preview_options };
+    }
+    if (caller.disable_web_page_preview !== undefined) {
+        return { disable_web_page_preview: caller.disable_web_page_preview };
+    }
+    const eligible = links.filter((link) => httpOrigin(link) !== undefined);
+    const mode = context.settings?.linkPreviews ?? "external";
+    if (eligible.length === 0 || mode === "all") {
+        return {};
+    }
+    if (mode === "none") {
+        return { link_preview_options: { is_disabled: true } };
+    }
+    const own = new Set([...(context.ownOrigins ?? []), ...(context.settings?.additionalOwnOrigins ?? [])].flatMap((value) => (httpOrigin(value) ? [httpOrigin(value)] : [])));
+    if (own.size === 0) {
+        return {};
+    }
+    const external = eligible.find((link) => !own.has(httpOrigin(link)));
+    return {
+        link_preview_options: external === undefined ? { is_disabled: true } : { url: external },
+    };
+}

package/dist/user-identity.d.ts

@@ -0,0 +1,28 @@
+/** How a sign-in identity came to be, as the `origin` property stores it. */
+export declare const USER_IDENTITY_ORIGINS: readonly ["invite", "sign_in", "link", "pairing", "channel"];
+export type UserIdentityOrigin = (typeof USER_IDENTITY_ORIGINS)[number];
+/**
+ * The built-in record of every external account a member signs in or talks with: their Neon Auth
+ * account, their SegmentStream (OIDC) accounts and their channel accounts, such as Telegram. Every
+ * ontology includes it next to `User` and `AgentChat`. Only the platform writes it, with history;
+ * no generated or authored action does. Reading it needs a permission that names it, such as
+ * `user_identity:read`: an entity wildcard (`*:read`, `*:*`) does not cover it.
+ *
+ * At most one live identity holds an account, and a member holds at most one live identity per
+ * provider other than `oidc`. Both are unique keys that hold a value only while the identity is
+ * live, and none once it is revoked.
+ */
+export declare const UserIdentity: import("./entity.js").DraftEntity<"user_identity", {
+    readonly provider: import("./property.js").Property<string, false, false>;
+    readonly issuer: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly subject: import("./property.js").Property<string, false, false>;
+    readonly username: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly display: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly origin: import("./property.js").Property<"link" | "invite" | "sign_in" | "pairing" | "channel", false, false>;
+    readonly revokedAt: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly accountKey: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, true>>;
+    readonly memberKey: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, true>>;
+}, {
+    readonly user: import("./relationship.js").OneRelationship<false, false, "user">;
+}, Readonly<Record<never, never>>, "actions">;
+export type UserIdentity = typeof UserIdentity.Type;

package/dist/user-identity.js

@@ -0,0 +1,106 @@
+import { entity } from "./entity.js";
+import { p } from "./property.js";
+import { rel } from "./relationship.js";
+/** How a sign-in identity came to be, as the `origin` property stores it. */
+export const USER_IDENTITY_ORIGINS = ["invite", "sign_in", "link", "pairing", "channel"];
+/**
+ * The built-in record of every external account a member signs in or talks with: their Neon Auth
+ * account, their SegmentStream (OIDC) accounts and their channel accounts, such as Telegram. Every
+ * ontology includes it next to `User` and `AgentChat`. Only the platform writes it, with history;
+ * no generated or authored action does. Reading it needs a permission that names it, such as
+ * `user_identity:read`: an entity wildcard (`*:read`, `*:*`) does not cover it.
+ *
+ * At most one live identity holds an account, and a member holds at most one live identity per
+ * provider other than `oidc`. Both are unique keys that hold a value only while the identity is
+ * live, and none once it is revoked.
+ */
+export const UserIdentity = entity("user_identity", {
+    id: "ent_user_identity",
+    label: "Sign-in identity",
+    plural: "Sign-in identities",
+    title: "subject",
+    description: "An external account a member signs in or talks with: their email sign-in, a SegmentStream " +
+        "account, or a chat account such as Telegram. The platform records them; nobody edits them.",
+    writes: "actions",
+    properties: {
+        provider: p.text({
+            managed: true,
+            description: "Who holds the account: neon-auth for email sign-in, oidc for SegmentStream sign-in, " +
+                "segmentstream for SegmentStream app tokens, or a chat provider such as telegram.",
+        }),
+        issuer: p.text({
+            optional: true,
+            managed: true,
+            description: "The OIDC issuer of an oidc account. Empty for every other provider.",
+        }),
+        subject: p.text({
+            managed: true,
+            description: "The account's id at the provider: the Neon Auth user id, the OIDC subject, or the " +
+                "chat user id.",
+        }),
+        username: p.text({
+            optional: true,
+            managed: true,
+            description: "The account's username at the provider, without @, when it has one.",
+        }),
+        display: p.text({
+            optional: true,
+            managed: true,
+            description: "The name the provider shows for the account, when it gives one.",
+        }),
+        origin: p.select([
+            {
+                value: "invite",
+                description: "The member's first sign-in claimed the invitation sent to their email.",
+            },
+            {
+                value: "sign_in",
+                label: "Sign-in",
+                description: "The member's first sign-in created the member or found them by it.",
+            },
+            {
+                value: "link",
+                description: "A signed-in member linked the account to themselves.",
+            },
+            {
+                value: "pairing",
+                description: "A signed-in member paired the chat account with a code.",
+            },
+            {
+                value: "channel",
+                description: "An open chat channel created the member for the chat account.",
+            },
+        ], { managed: true, description: "How the account came to belong to the member." }),
+        revokedAt: p.timestamp({
+            optional: true,
+            managed: true,
+            label: "Revoked",
+            description: "When the account stopped working for the member. Empty while it is live.",
+        }),
+        accountKey: p.text({
+            optional: true,
+            unique: true,
+            managed: true,
+            label: "Account key",
+            description: "provider, issuer and subject while the identity is live, so that one account belongs " +
+                "to one live identity. Empty once revoked.",
+        }),
+        memberKey: p.text({
+            optional: true,
+            unique: true,
+            managed: true,
+            label: "Member key",
+            description: "The member and provider while the identity is live, for providers that allow one live " +
+                "account per member. Empty once revoked, and for oidc, which allows several.",
+        }),
+    },
+    relationships: {
+        // By name, so that an ontology rebuilt with the deployed `user` still resolves it.
+        user: rel.one("user", {
+            inverse: "identities",
+            onDelete: "cascade",
+            phrase: ["belongs to", "signs in with"],
+            description: "The member the account belongs to.",
+        }),
+    },
+});

package/dist/user.d.ts

@@ -0,0 +1,75 @@
+import { Effect } from "effect";
+import type { Actions } from "./action.js";
+import { type Entity, type InvocableActions, type NoActions, type NoRelationships, type RecordRef } from "./entity.js";
+import type { ActionRejected, Conflict, NotFound } from "./errors.js";
+import { OntologyWrites } from "./runtime.js";
+/**
+ * The built-in user: an app member who signs in with the workspace's Neon Auth (or, during the
+ * transition, with SegmentStream), or a service principal that authenticates with an API key. Every
+ * ontology includes it, and entities reference it like any other (`rel.one(User, …)`). Principals
+ * are users, so `principal.id` is a user id.
+ *
+ * The sign-in fields are managed: the ontology service links a member on first sign-in by the
+ * token's subject and records when they last signed in. A member's external accounts are the
+ * built-in `UserIdentity` records (`identities`); `identityProvider` and `identitySubject` keep a
+ * member's first sign-in for earlier SDKs, and a service's identity. Role assignments and API keys are kept by
+ * the service beside this table. Role assignments are changed through the `user` actions, the
+ * console or the CLI, and read as the record's managed, read-only `roles`.
+ */
+declare const UserEntity: import("./entity.js").DraftEntity<"user", {
+    readonly name: import("./property.js").Property<string, false, false>;
+    readonly email: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, true>>;
+    readonly kind: import("./property.js").Property<"member" | "service", false, false>;
+    readonly active: import("./property.js").Property<boolean, true, false>;
+    readonly identityProvider: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly identitySubject: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly lastSignInAt: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly roles: import("./property.js").Property<readonly string[], false, false>;
+}, import("./entity.js").Relationships, Readonly<Record<never, never>>, "generated">;
+type UserRecord = typeof UserEntity.Type;
+/**
+ * The member writes of the `User` handle, for action handlers: they require {@link OntologyWrites},
+ * which `prepare` never has. They are the generated `user` actions' own writes, in the action's
+ * transaction, with history under the action's name and principal; only members are managed, so a
+ * service or an unknown id fails with NotFound. Roles are the ontology's declared roles; one it does
+ * not declare, or `member`, is ActionRejected. Each returns the user with its new `roles`.
+ */
+export interface UserMemberWrites {
+    /** Grants roles; a role the member holds changes nothing. */
+    grantRoles(record: RecordRef, roles: ReadonlyArray<string>): Effect.Effect<UserRecord, ActionRejected | NotFound, OntologyWrites>;
+    /** Revokes roles, or every role; a role the member does not hold changes nothing. */
+    revokeRoles(record: RecordRef, roles: ReadonlyArray<string> | "all"): Effect.Effect<UserRecord, ActionRejected | NotFound, OntologyWrites>;
+    /**
+     * Creates a member for an email no user has, linked at their first sign-in; a known email fails
+     * with Conflict. The name defaults to the email.
+     */
+    invite(input: {
+        readonly email: string;
+        readonly name?: string;
+        readonly roles?: ReadonlyArray<string>;
+    }): Effect.Effect<UserRecord, ActionRejected | Conflict, OntologyWrites>;
+    /** Deactivates a member, which ends their sessions, or reactivates one. */
+    setActive(record: RecordRef, active: boolean): Effect.Effect<UserRecord, NotFound, OntologyWrites>;
+    /**
+     * Emails an active member a link that signs them in and opens `returnTo`, a path of the app, `/`
+     * by default. The email is `template`, one of the ontology's `emails` filled with `values`; or,
+     * without one, the platform's own: the invitation for a member who has not signed in yet, else
+     * the sign-in link. It is sent once the action commits; a send that fails never fails the action.
+     * An inactive member, an unknown email, a missing or unused value, or a path outside the app is
+     * ActionRejected.
+     */
+    sendSignInLink(record: RecordRef, options?: {
+        readonly template?: string;
+        readonly returnTo?: string;
+        readonly values?: Readonly<Record<string, string>>;
+    }): Effect.Effect<void, ActionRejected | NotFound, OntologyWrites>;
+}
+/** The built-in user's handle with actions `A`: its entity, and the member writes. */
+export type UserHandle<A extends object> = Entity<"user", typeof UserEntity.properties, NoRelationships, A> & UserMemberWrites;
+/** `User.actions((self) => ({ … }))`, whose `self` has the member writes too. */
+interface UserActionsBuilder {
+    <const A extends Actions>(define: (self: UserHandle<NoActions>) => A): UserHandle<InvocableActions<A>>;
+}
+export declare const User: UserHandle<UserActionsBuilder>;
+export type User = UserRecord;
+export {};

package/dist/user.js

@@ -0,0 +1,111 @@
+import { Effect } from "effect";
+import { nameToWire } from "./authoring-names.js";
+import { recordFromWire } from "./authoring-records.js";
+import { entity, } from "./entity.js";
+import { p } from "./property.js";
+import { OntologyWrites } from "./runtime.js";
+/**
+ * The built-in user: an app member who signs in with the workspace's Neon Auth (or, during the
+ * transition, with SegmentStream), or a service principal that authenticates with an API key. Every
+ * ontology includes it, and entities reference it like any other (`rel.one(User, …)`). Principals
+ * are users, so `principal.id` is a user id.
+ *
+ * The sign-in fields are managed: the ontology service links a member on first sign-in by the
+ * token's subject and records when they last signed in. A member's external accounts are the
+ * built-in `UserIdentity` records (`identities`); `identityProvider` and `identitySubject` keep a
+ * member's first sign-in for earlier SDKs, and a service's identity. Role assignments and API keys are kept by
+ * the service beside this table. Role assignments are changed through the `user` actions, the
+ * console or the CLI, and read as the record's managed, read-only `roles`.
+ */
+const UserEntity = entity("user", {
+    id: "ent_user",
+    label: "User",
+    plural: "Users",
+    title: "name",
+    description: "A person or service that uses the app. Members sign in to the app; " +
+        "services authenticate with an API key.",
+    properties: {
+        name: p.text({ description: "The name shown in the app." }),
+        email: p.email({
+            optional: true,
+            unique: true,
+            description: "The member's sign-in address. Services have none.",
+        }),
+        kind: p.select([
+            {
+                value: "member",
+                label: "Member",
+                description: "A person who signs in to the app.",
+            },
+            {
+                value: "service",
+                label: "Service",
+                description: "A program that authenticates with an API key.",
+            },
+        ], { managed: true, description: "Whether the user is a person or a program." }),
+        active: p.boolean({
+            default: true,
+            managed: true,
+            description: "Inactive users cannot sign in or run actions.",
+        }),
+        identityProvider: p.text({
+            renamedFrom: "identityProvider",
+            optional: true,
+            managed: true,
+            description: "Who authenticates a service, or signed a member in first, for example neon-auth. A " +
+                "member's accounts are their sign-in identities.",
+        }),
+        identitySubject: p.text({
+            renamedFrom: "identitySubject",
+            optional: true,
+            managed: true,
+            description: "The user's id at that identity provider: the subject of their token.",
+        }),
+        // Optional so that a table created before it gains the column without a backfill: a member
+        // who has not signed in since simply has none.
+        lastSignInAt: p.timestamp({
+            renamedFrom: "lastSignInAt",
+            optional: true,
+            managed: true,
+            label: "Last sign-in",
+            description: "When the member last signed in to the app. Empty until they do.",
+        }),
+        // Read from the role assignments beside the table, in the statement that reads the record; it
+        // has no column, so adding it needed no migration.
+        roles: p.list(p.text(), {
+            managed: true,
+            description: "The roles assigned to the member, without the implicit member role.",
+        }),
+    },
+    indexes: [{ properties: ["identityProvider", "identitySubject"], unique: true }],
+});
+function idOf(record) {
+    return typeof record === "string" ? record : record.id;
+}
+function written(operation) {
+    return Effect.flatMap(OntologyWrites, operation).pipe(Effect.map((record) => recordFromWire(record, UserEntity.definition)));
+}
+const memberWrites = {
+    grantRoles: (record, roles) => written((writes) => writes.grantUserRoles({ id: idOf(record), roles: roles.map(nameToWire) })),
+    revokeRoles: (record, roles) => written((writes) => writes.revokeUserRoles({
+        id: idOf(record),
+        roles: roles === "all" ? "all" : roles.map(nameToWire),
+    })),
+    invite: ({ email, name, roles }) => written((writes) => writes.inviteUser({ email, name, roles: roles?.map(nameToWire) })),
+    setActive: (record, active) => written((writes) => writes.setUserActive({ id: idOf(record), active })),
+    sendSignInLink: (record, options = {}) => Effect.flatMap(OntologyWrites, (writes) => writes.sendUserSignInLink({
+        id: idOf(record),
+        template: options.template === undefined ? undefined : nameToWire(options.template),
+        returnTo: options.returnTo,
+        values: options.values,
+    })),
+};
+export const User = {
+    ...UserEntity,
+    ...memberWrites,
+    // Every form shares the definition, which is how defineOntology recognises the built-in.
+    actions: (define) => ({
+        ...UserEntity.actions((self) => define({ ...self, ...memberWrites })),
+        ...memberWrites,
+    }),
+};

package/dist/warehouse-backed.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedEntity } from "./analyze.js";
+import type { DiagnosticCode } from "./diagnostics.js";
+type Report = (code: DiagnosticCode, path: string, message: string) => void;
+/** Cross-field validation runs after relationships have resolved their target entities. */
+export declare function checkWarehouseSource(entities: ReadonlyArray<ResolvedEntity>, report: Report): void;
+export {};