@segmentstream/app 0.0.0-stage → 0.38.0

package/dist/ontology.js

@@ -0,0 +1,367 @@
+import { SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
+import { metricQueryPoster, withEarlierQueryMetricsName, } from "./legacy.js";
+import { actionInputToWire, encodeWhere, editsFromWire, includeToWire, queryToWire, recordFromWire, responseFromWire, returnsUserRecord, } from "./ontology-wire.js";
+import { toCamelCase, toReversibleCamelCase, toSnakeCase } from "./ontology-names.js";
+import { createBlobStorageClient } from "./storage.js";
+const ENTITY_NAME = /^[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*$/;
+const ACTION_NAME = ENTITY_NAME;
+/** @internal The ontology service's metric query route, model-level and per entity; never an entity. */
+export const QUERY_METRICS_ROUTE = "query_metrics";
+/** Names a caller may probe on any object; never an entity or an action. */
+const RESERVED = new Set([
+    "then",
+    "catch",
+    "finally",
+    "constructor",
+    "toString",
+    "toLocaleString",
+    "valueOf",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+]);
+// Node's inspection hook is Symbol.for("nodejs.util.inspect.custom"). Symbols
+// are ignored by the proxies below; the string "inspect" is a valid domain name.
+/**
+ * Entities and actions exist only in the app's types, so the client resolves them by name when
+ * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
+ */
+export function createOntologyClient(transport) {
+    const entities = new Map();
+    const catalogReader = createCatalogReader(transport);
+    // Every call, metric queries included, carries the user's session for the service to check.
+    const postMetricQuery = metricQueryPoster(QUERY_METRICS_ROUTE, (path, body, signal) => dispatch(catalogReader.transport, "POST", path, body, signal));
+    const queryMetrics = async (request, options = {}) => modelMetricQueryResultFromWire(await payloadOf(await postMetricQuery("", metricQueryToWire(request), options.signal)));
+    const model = {
+        queryMetrics,
+        ...withEarlierQueryMetricsName(queryMetrics),
+    };
+    return new Proxy(Object.create(null), {
+        get(_target, property) {
+            if (typeof property === "string" && Object.hasOwn(model, property)) {
+                return model[property];
+            }
+            if (typeof property !== "string" || RESERVED.has(property) || !ENTITY_NAME.test(property)) {
+                return undefined;
+            }
+            let client = entities.get(property);
+            if (client === undefined) {
+                const entity = toSnakeCase(property);
+                // Names are relative to the entity and convert as record fields do.
+                const queryEntityMetrics = async (request, options = {}) => metricQueryResultFromWire(await payloadOf(await postMetricQuery(`/${entity}`, metricQueryToWire(request), options.signal)), toCamelCase);
+                client = {
+                    ...entityClient(entity, catalogReader.transport, catalogReader.getCatalog),
+                    queryMetrics: queryEntityMetrics,
+                    ...withEarlierQueryMetricsName(queryEntityMetrics),
+                };
+                entities.set(property, client);
+            }
+            return client;
+        },
+    });
+}
+function createCatalogReader(transport) {
+    let catalogPromise;
+    let catalogHash;
+    const observedTransport = {
+        async fetch(path, init) {
+            const response = await transport.fetch(path, init);
+            const hash = response.headers.get("x-ontology-hash");
+            if (catalogHash !== undefined && hash !== null && hash !== catalogHash) {
+                catalogPromise = undefined;
+                catalogHash = undefined;
+            }
+            return response;
+        },
+    };
+    async function readCatalog() {
+        try {
+            const catalog = await send(observedTransport, "GET", "", undefined, undefined);
+            catalogHash = catalog.hash;
+            return catalog;
+        }
+        catch (error) {
+            catalogPromise = undefined;
+            throw error;
+        }
+    }
+    function getCatalog() {
+        catalogPromise ??= readCatalog();
+        return catalogPromise;
+    }
+    return { transport: observedTransport, getCatalog };
+}
+function entityClient(entity, transport, getCatalog) {
+    const base = `/${entity}`;
+    const storage = createBlobStorageClient(transport);
+    const actionCalls = new Map();
+    const runAction = async (name, input, options = {}) => {
+        const action = toSnakeCase(name);
+        const catalog = await getCatalog();
+        const wireResponse = await send(transport, "POST", `${base}/actions/${encodeURIComponent(action)}`, {
+            input: actionInputToWire(input, entity, action, catalog),
+            ...([options.validateOnly, options.idempotencyKey, options.createIntent].every((value) => value === undefined)
+                ? {}
+                : {
+                    options: {
+                        ...(options.validateOnly === undefined
+                            ? {}
+                            : { validate_only: options.validateOnly }),
+                        ...(options.idempotencyKey === undefined
+                            ? {}
+                            : { idempotency_key: options.idempotencyKey }),
+                        ...(options.createIntent === undefined
+                            ? {}
+                            : { create_intent: options.createIntent }),
+                    },
+                }),
+        }, options.signal);
+        const response = { ...wireResponse, edits: editsFromWire(wireResponse.edits, catalog) };
+        if (action === "create" || action === "update" || returnsUserRecord(entity, action)) {
+            return { ...response, result: recordFromWire(response.result, entity, catalog) };
+        }
+        if (action.startsWith("upsert_by_") &&
+            response.result !== null &&
+            typeof response.result === "object" &&
+            !Array.isArray(response.result)) {
+            return {
+                ...response,
+                result: {
+                    ...response.result,
+                    record: recordFromWire(response.result.record, entity, catalog),
+                },
+            };
+        }
+        return response;
+    };
+    const actions = new Proxy(Object.create(null), {
+        get(_target, property) {
+            if (typeof property !== "string" || RESERVED.has(property) || !ACTION_NAME.test(property)) {
+                return undefined;
+            }
+            let call = actionCalls.get(property);
+            if (call === undefined) {
+                call = (input, options) => runAction(property, input, options);
+                actionCalls.set(property, call);
+            }
+            return call;
+        },
+    });
+    return {
+        files: {
+            download: (id, property, options) => storage.download(entity, id, property, options),
+        },
+        find: async (query = {}, options = {}) => {
+            const catalog = await getCatalog();
+            const where = await encodeWhere({ where: query.where, entity, getCatalog });
+            const search = findParameters({ ...query, where }).toString();
+            const page = await send(transport, "GET", search === "" ? base : `${base}?${search}`, undefined, options.signal);
+            validateProjection(page, query.select);
+            return {
+                ...page,
+                items: page.items.map((record) => recordFromWire(record, entity, catalog)),
+            };
+        },
+        query: async (query = {}, options = {}) => {
+            const catalog = await getCatalog();
+            const where = await encodeWhere({ where: query.where, entity, getCatalog });
+            const page = await send(transport, "POST", `${base}/query`, queryToWire({ ...query, where }), options.signal);
+            validateProjection(page, query.select);
+            return {
+                ...page,
+                items: page.items.map((record) => recordFromWire(record, entity, catalog)),
+            };
+        },
+        get: (id, options = {}) => {
+            const encodedId = recordId(id);
+            return getCatalog().then(async (catalog) => recordFromWire(await send(transport, "GET", `${base}/${encodedId}`, undefined, options.signal), entity, catalog));
+        },
+        history: (id, options = {}) => {
+            const search = new URLSearchParams();
+            if (options.after !== undefined) {
+                search.set("after", options.after);
+            }
+            if (options.limit !== undefined) {
+                search.set("limit", String(options.limit));
+            }
+            const encoded = search.toString();
+            const suffix = encoded === "" ? "" : `?${encoded}`;
+            return send(transport, "GET", `${base}/${recordId(id)}/history${suffix}`, undefined, options.signal);
+        },
+        actions,
+        action: (name, input, options) => {
+            if (!ACTION_NAME.test(name)) {
+                throw new TypeError(`"${name}" is not an action name.`);
+            }
+            return runAction(name, input, options);
+        },
+    };
+}
+/** A projected response must never masquerade as a complete typed record (or vice versa). */
+function validateProjection(page, selection) {
+    const invalid = selection === undefined
+        ? page.projected !== undefined
+        : page.projected !== true ||
+            page.items.some((record) => typeof record.id !== "string" ||
+                selection.some((field) => !Object.hasOwn(record, toSnakeCase(field))));
+    if (invalid) {
+        throw new SegmentStreamApiError({
+            code: "ontology_invalid_response",
+            status: 502,
+            detail: "The ontology service returned an incompatible record projection.",
+            retryable: false,
+        });
+    }
+}
+function recordId(id) {
+    if (typeof id !== "string" || id === "") {
+        throw new TypeError("A record id is a non-empty string.");
+    }
+    return encodeURIComponent(id);
+}
+/** `find` sends the query as URL parameters: `where` as JSON, `orderBy` as `field:direction`. */
+export function findParameters(query) {
+    const search = new URLSearchParams();
+    if (query.select !== undefined) {
+        search.set("select", query.select.map(toSnakeCase).join(","));
+    }
+    if (query.where !== undefined) {
+        search.set("where", JSON.stringify(query.where));
+    }
+    if (query.orderBy !== undefined && query.orderBy.length > 0) {
+        search.set("order_by", query.orderBy
+            .map(({ field, direction }) => `${toSnakeCase(field)}:${direction ?? "asc"}`)
+            .join(","));
+    }
+    if (query.include !== undefined) {
+        const relationships = Object.entries(includeToWire(query.include))
+            .filter(([, included]) => included === true)
+            .map(([name]) => name);
+        if (relationships.length > 0) {
+            search.set("include", relationships.join(","));
+        }
+    }
+    if (query.after !== undefined) {
+        search.set("after", query.after);
+    }
+    if (query.limit !== undefined) {
+        search.set("limit", String(query.limit));
+    }
+    return search;
+}
+/**
+ * Metric queries keep their camelCase protocol keys and filter values; the names in them convert
+ * to snake_case one segment at a time.
+ */
+function metricQueryToWire(request) {
+    return {
+        ...request,
+        ...(request.dimensions === undefined
+            ? {}
+            : { dimensions: request.dimensions.map(toSnakeCase) }),
+        metrics: request.metrics.map(toSnakeCase),
+        ...(request.granularityOf === undefined
+            ? {}
+            : { granularityOf: toSnakeCase(request.granularityOf) }),
+        ...(request.filters === undefined
+            ? {}
+            : {
+                filters: request.filters.map((filter) => ({
+                    ...filter,
+                    dimension: toSnakeCase(filter.dimension),
+                })),
+            }),
+        ...(request.orderBy === undefined
+            ? {}
+            : {
+                orderBy: request.orderBy.map((order) => ({
+                    ...order,
+                    ...(order.dimension === undefined ? {} : { dimension: toSnakeCase(order.dimension) }),
+                    ...(order.metric === undefined ? {} : { metric: toSnakeCase(order.metric) }),
+                })),
+            }),
+    };
+}
+/**
+ * Field names, the filters each metric applied, a balance's dimension, a model metric's inputs and
+ * row keys come back camelCase per segment; `execution` is passed on as sent.
+ */
+function metricQueryResultFromWire(result, decodeName) {
+    return {
+        ...result,
+        fields: result.fields.map((field) => ({
+            ...field,
+            name: decodeName(field.name),
+            ...(field.filters === undefined ? {} : { filters: field.filters.map(decodeName) }),
+            ...(field.balanceOver === undefined ? {} : { balanceOver: decodeName(field.balanceOver) }),
+            ...(field.inputs === undefined ? {} : { inputs: field.inputs.map(decodeName) }),
+        })),
+        rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [decodeName(name), value]))),
+    };
+}
+/**
+ * Model-level names keep an `_` before a digit; the entities in `sources` and the dimensions in
+ * `periods` convert too.
+ */
+function modelMetricQueryResultFromWire(wire) {
+    const result = metricQueryResultFromWire(wire, toReversibleCamelCase);
+    const { sources, periods } = result.execution;
+    if (sources === undefined && periods === undefined) {
+        return result;
+    }
+    return {
+        ...result,
+        execution: {
+            ...result.execution,
+            ...(sources === undefined
+                ? {}
+                : {
+                    sources: sources.map((source) => ({
+                        ...source,
+                        entity: toReversibleCamelCase(source.entity),
+                    })),
+                }),
+            ...(periods === undefined
+                ? {}
+                : {
+                    periods: periods.map((period) => ({
+                        ...period,
+                        dimension: toReversibleCamelCase(period.dimension),
+                    })),
+                }),
+        },
+    };
+}
+async function send(transport, method, path, body, signal) {
+    const payload = await payloadOf(await dispatch(transport, method, path, body, signal));
+    return responseFromWire({ method, path, payload });
+}
+/** Sends one request to the ontology service, its body as JSON. */
+function dispatch(transport, method, path, body, signal) {
+    const headers = new Headers({ accept: "application/json" });
+    if (body !== undefined) {
+        headers.set("content-type", "application/json");
+    }
+    return transport.fetch(path, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        ...(signal === undefined ? {} : { signal }),
+    });
+}
+/** The service's JSON answer, or the error it answered with. */
+async function payloadOf(response) {
+    const payload = await readJson(response);
+    if (!response.ok) {
+        throw apiErrorFrom(response.status, payload, "The ontology service rejected the request.");
+    }
+    if (payload === null) {
+        throw new SegmentStreamApiError({
+            code: "ontology_invalid_response",
+            status: 502,
+            detail: "The ontology service answered without a JSON body.",
+            retryable: true,
+        });
+    }
+    return payload;
+}

package/dist/pages.d.ts

@@ -0,0 +1,6 @@
+/** The app's page where a signed-in member decides whether an agent may act for them. */
+export declare const CONSENT_PAGE = "/oauth/consent";
+/** The app's page where a signed-in member links their chat account to the workspace agent. */
+export declare const AGENT_CONNECT_PAGE = "/agent/connect";
+/** The Route Handler the agent connect page's form posts to. */
+export declare const AGENT_CONNECT_HANDLER = "/api/agent/connect";

package/dist/pages.js

@@ -0,0 +1,6 @@
+/** The app's page where a signed-in member decides whether an agent may act for them. */
+export const CONSENT_PAGE = "/oauth/consent";
+/** The app's page where a signed-in member links their chat account to the workspace agent. */
+export const AGENT_CONNECT_PAGE = "/agent/connect";
+/** The Route Handler the agent connect page's form posts to. */
+export const AGENT_CONNECT_HANDLER = "/api/agent/connect";

package/dist/parameters.d.ts

@@ -0,0 +1,55 @@
+export declare const PARAMETER_TYPES: readonly ["STRING", "INT64", "FLOAT64", "NUMERIC", "BIGNUMERIC", "BOOL", "DATE", "DATETIME", "TIMESTAMP"];
+export type ParameterType = (typeof PARAMETER_TYPES)[number];
+declare const TYPED: unique symbol;
+/** A value with an explicit warehouse type, created with the `sql` helpers. */
+export interface TypedParameter {
+    readonly [TYPED]: true;
+    readonly type: ParameterType;
+    readonly value?: string;
+    readonly values?: readonly string[];
+}
+/** A value bound to a named `@parameter`; never spliced into the SQL text. */
+export type QueryParameterValue = string | number | bigint | boolean | Date | TypedParameter | ReadonlyArray<string | number | bigint | boolean | Date>;
+export type QueryParameters = Readonly<Record<string, QueryParameterValue>>;
+/** The wire form the SegmentStream API accepts. */
+export type EncodedParameter = {
+    readonly name: string;
+    readonly type: ParameterType;
+    readonly value: string;
+} | {
+    readonly name: string;
+    readonly type: ParameterType;
+    readonly values: readonly string[];
+};
+/**
+ * Explicit parameter types for values JavaScript cannot express unambiguously.
+ *
+ * ```ts
+ * await segmentstream.warehouse.query(
+ *   "SELECT * FROM gold.orders WHERE order_date >= @from AND amount > @minimum",
+ *   { params: { from: sql.date("2026-09-01"), minimum: sql.numeric("10.50") } },
+ * );
+ * ```
+ */
+export declare const sql: {
+    readonly string: (value: string) => TypedParameter;
+    readonly int64: (value: number | bigint | string) => TypedParameter;
+    readonly float64: (value: number) => TypedParameter;
+    readonly numeric: (value: string | number) => TypedParameter;
+    readonly bignumeric: (value: string | number) => TypedParameter;
+    readonly bool: (value: boolean) => TypedParameter;
+    /** A calendar date, `YYYY-MM-DD`; a `Date` uses its UTC day. */
+    readonly date: (value: string | Date) => TypedParameter;
+    /** A civil date and time without a time zone, `YYYY-MM-DDTHH:MM:SS[.ffffff]`. */
+    readonly datetime: (value: string) => TypedParameter;
+    readonly timestamp: (value: string | Date) => TypedParameter;
+    /** An array of one element type; needed for empty arrays and non-default element types. */
+    readonly array: (type: ParameterType, values: ReadonlyArray<string | number | bigint | boolean | Date>) => {
+        [TYPED]: true;
+        type: "STRING" | "INT64" | "FLOAT64" | "NUMERIC" | "BIGNUMERIC" | "BOOL" | "DATE" | "DATETIME" | "TIMESTAMP";
+        values: string[];
+    };
+};
+/** Infers warehouse types for named parameters and validates their names. */
+export declare function encodeParameters(parameters: QueryParameters | undefined): EncodedParameter[];
+export {};

package/dist/parameters.js

@@ -0,0 +1,118 @@
+export const PARAMETER_TYPES = [
+    "STRING",
+    "INT64",
+    "FLOAT64",
+    "NUMERIC",
+    "BIGNUMERIC",
+    "BOOL",
+    "DATE",
+    "DATETIME",
+    "TIMESTAMP",
+];
+const TYPED = Symbol.for("segmentstream.app.queryParameter");
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+function typed(type, value) {
+    return { [TYPED]: true, type, value };
+}
+function isoDate(value, name) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError(`sql.${name}() received an invalid Date.`);
+        }
+        return value.toISOString().slice(0, 10);
+    }
+    return value;
+}
+function timestamp(value) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError("sql.timestamp() received an invalid Date.");
+        }
+        return value.toISOString();
+    }
+    return value;
+}
+/**
+ * Explicit parameter types for values JavaScript cannot express unambiguously.
+ *
+ * ```ts
+ * await segmentstream.warehouse.query(
+ *   "SELECT * FROM gold.orders WHERE order_date >= @from AND amount > @minimum",
+ *   { params: { from: sql.date("2026-09-01"), minimum: sql.numeric("10.50") } },
+ * );
+ * ```
+ */
+export const sql = {
+    string: (value) => typed("STRING", value),
+    int64: (value) => typed("INT64", String(value)),
+    float64: (value) => typed("FLOAT64", String(value)),
+    numeric: (value) => typed("NUMERIC", String(value)),
+    bignumeric: (value) => typed("BIGNUMERIC", String(value)),
+    bool: (value) => typed("BOOL", String(value)),
+    /** A calendar date, `YYYY-MM-DD`; a `Date` uses its UTC day. */
+    date: (value) => typed("DATE", isoDate(value, "date")),
+    /** A civil date and time without a time zone, `YYYY-MM-DDTHH:MM:SS[.ffffff]`. */
+    datetime: (value) => typed("DATETIME", value),
+    timestamp: (value) => typed("TIMESTAMP", timestamp(value)),
+    /** An array of one element type; needed for empty arrays and non-default element types. */
+    array: (type, values) => ({
+        [TYPED]: true,
+        type,
+        values: values.map((value) => scalar(value, "array element").value),
+    }),
+};
+function isTyped(value) {
+    return typeof value === "object" && value !== null && TYPED in value;
+}
+function scalar(value, name) {
+    switch (typeof value) {
+        case "string":
+            return { type: "STRING", value };
+        case "boolean":
+            return { type: "BOOL", value: String(value) };
+        case "bigint":
+            return { type: "INT64", value: String(value) };
+        case "number":
+            return Number.isSafeInteger(value)
+                ? { type: "INT64", value: String(value) }
+                : { type: "FLOAT64", value: String(value) };
+        default:
+            if (value instanceof Date) {
+                return { type: "TIMESTAMP", value: timestamp(value) };
+            }
+            throw new TypeError(`Query parameter "${name}" must be a string, number, bigint, boolean, Date, or sql.* value; ` +
+                "use SQL NULL in the query text instead of a null parameter.");
+    }
+}
+/** Infers warehouse types for named parameters and validates their names. */
+export function encodeParameters(parameters) {
+    if (parameters === undefined) {
+        return [];
+    }
+    return Object.entries(parameters).map(([name, value]) => {
+        if (!NAME.test(name)) {
+            throw new TypeError(`Query parameter name "${name}" must start with a letter or underscore and contain only letters, digits, and underscores.`);
+        }
+        if (isTyped(value)) {
+            return value.values === undefined
+                ? { name, type: value.type, value: value.value ?? "" }
+                : { name, type: value.type, values: value.values };
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                throw new TypeError(`Query parameter "${name}" is an empty array; use sql.array(type, []) to declare its element type.`);
+            }
+            const items = value.map((item) => scalar(item, name));
+            const type = items.every((item) => item.type === items[0]?.type)
+                ? items[0].type
+                : items.every((item) => item.type === "INT64" || item.type === "FLOAT64")
+                    ? "FLOAT64"
+                    : undefined;
+            if (type === undefined) {
+                throw new TypeError(`Query parameter "${name}" mixes element types; use sql.array(type, values).`);
+            }
+            return { name, type, values: items.map((item) => item.value) };
+        }
+        return { name, ...scalar(value, name) };
+    });
+}

package/dist/permissions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Permissions are `<entity>:<verb>` strings, such as `lead:changeStatus`. A role may use `*` for the
+ * entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
+ * holds a wildcard. A wildcard entity does not cover the built-in `agent_chat`: only a permission
+ * that names it does. Of the built-in `user` it covers only `read` and `update`, so member management
+ * (`user:invite`, `user:grant_roles`, …) and authored actions on `user` need `user:<verb>` or `user:*`.
+ *
+ * The matching rule is the ontology service's, copied from `@segmentstream/ontology`
+ * (`src/permissions.ts`) so that the app SDK and its browser components do not depend on the
+ * ontology runtime. Keep the two in step.
+ */
+/** Whether a granted permission, which may hold wildcards, covers the required one. */
+export declare function grants(granted: string, required: string): boolean;
+/** Anything that holds permissions, such as the signed-in user. */
+export interface PermissionHolder {
+    readonly permissions: ReadonlyArray<string>;
+}
+/** Whether one of the holder's permissions equals `required` or covers it through a wildcard. */
+export declare function isAllowed(required: string, holder: PermissionHolder): boolean;

package/dist/permissions.js

@@ -0,0 +1,55 @@
+/**
+ * Permissions are `<entity>:<verb>` strings, such as `lead:changeStatus`. A role may use `*` for the
+ * entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
+ * holds a wildcard. A wildcard entity does not cover the built-in `agent_chat`: only a permission
+ * that names it does. Of the built-in `user` it covers only `read` and `update`, so member management
+ * (`user:invite`, `user:grant_roles`, …) and authored actions on `user` need `user:<verb>` or `user:*`.
+ *
+ * The matching rule is the ontology service's, copied from `@segmentstream/ontology`
+ * (`src/permissions.ts`) so that the app SDK and its browser components do not depend on the
+ * ontology runtime. Keep the two in step.
+ */
+import { toSnakeCase } from "./ontology-names.js";
+const WILDCARD = "*";
+/** Entities only a permission that names them covers; `*:read` and `*:*` grant nothing on them. */
+const EXPLICIT_GRANT_ENTITIES = new Set(["agent_chat"]);
+/** Entities of which a wildcard entity covers only the listed verbs. */
+const WILDCARD_ENTITY_VERBS = new Map([
+    ["user", new Set(["read", "update"])],
+]);
+function wildcardEntityCovers(entity, verb) {
+    if (EXPLICIT_GRANT_ENTITIES.has(entity)) {
+        return false;
+    }
+    return WILDCARD_ENTITY_VERBS.get(entity)?.has(verb) ?? true;
+}
+/** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
+const PERMISSION = /^(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*)$/;
+function parsePermission(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const match = PERMISSION.exec(value);
+    return match === null
+        ? undefined
+        : { entity: toSnakeCase(match[1]), verb: toSnakeCase(match[2]) };
+}
+/** Whether a granted permission, which may hold wildcards, covers the required one. */
+export function grants(granted, required) {
+    const held = parsePermission(granted);
+    const wanted = parsePermission(required);
+    if (held === undefined || wanted === undefined) {
+        return false;
+    }
+    return ((held.entity === WILDCARD
+        ? wildcardEntityCovers(wanted.entity, wanted.verb)
+        : held.entity === wanted.entity) &&
+        (held.verb === WILDCARD || held.verb === wanted.verb));
+}
+/** Whether one of the holder's permissions equals `required` or covers it through a wildcard. */
+export function isAllowed(required, holder) {
+    // Keep the ontology matcher semantics, including invalid-input rejection,
+    // while avoiding repeated parsing of preceding grants for exact matches.
+    return ((holder.permissions.includes(required) && grants(required, required)) ||
+        holder.permissions.some((granted) => grants(granted, required)));
+}

package/dist/pkce.d.ts

@@ -0,0 +1,8 @@
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function base64UrlDecode(value: string): Uint8Array;
+/** A URL-safe random value carrying `byteLength` bytes of entropy. */
+export declare function randomToken(byteLength?: number): string;
+/** The RFC 7636 S256 code challenge for a code verifier. */
+export declare function createCodeChallenge(codeVerifier: string): Promise<string>;
+/** Compares two strings without short-circuiting on the first differing character. */
+export declare function constantTimeEqual(left: string, right: string): boolean;