@phis/contracts 0.3.1 → 0.5.0

package/dist/references.d.ts

@@ -0,0 +1,130 @@
+/**
+ * What one side of the house means when it points at a Page: `@phis/server/references:v1`.
+ *
+ * The codec stood in two copies, in phis-ui and in phi-server, for the same reason the CMS instance id
+ * did before it moved here -- and with the same risk, which is that two sides agreeing byte for byte is
+ * a thing nobody notices stopping. It is one file now.
+ *
+ * **A reference is short because a Page already has a name.** It used to be base64-encoded JSON carrying
+ * the whole identity, which for a Module Page ran to 98 characters in every Markdown body that linked to
+ * one. The envelope was never protection -- it is encoding, not a signature, and the server revalidates
+ * Site and Area regardless -- so what it actually bought was a payload the server could unpack. It no
+ * longer needs to: a Module Page is named by the CMS Page id derived from `(ownerModuleId, presetKey)`,
+ * which is recomputable rather than allocated and therefore stands before any row does.
+ *
+ * The two variants are shaped differently on purpose. A Site Page carries its Page Scope id as a plain
+ * number because the server writes that number into a foreign key with `ON DELETE RESTRICT`: the
+ * database itself refuses to delete a Page something still points at, and nothing derived could take
+ * that column's place. A Module Page has no row to point a foreign key at -- the Site may never have
+ * touched it -- so it carries the derived id, which the server passes on without ever unpacking.
+ */
+import { type PhiCmsAreaKey, type PhiCmsInstanceId } from "./cms.js";
+export declare const PHIS_INTERNAL_PAGE_SCHEME: "phis:page/";
+export declare const PHIS_INTERNAL_ASSET_SCHEME: "phis:asset/";
+/**
+ * A Module Page's identity, hashed to one token both sides can recompute.
+ *
+ * Recomputable rather than allocated, so no row has to exist before the Page can be addressed, and it
+ * never mentions the path: reassigning where a Page answers leaves everything pointing at it alone.
+ */
+export declare function createPhiPresetCmsPageId(identity: {
+    ownerModuleId: string;
+    presetKey: string;
+}): PhiCmsInstanceId;
+/** What a reference says, once read. A Module Page answers with its id, never with what was hashed. */
+export type PhiPageTarget = {
+    kind: "site";
+    pageScopeId: number;
+} | {
+    kind: "module";
+    pageId: PhiCmsInstanceId;
+};
+/** What a reference is made from. The Module variant differs: the identity goes in, the id comes out. */
+export type PhiPageTargetInput = {
+    kind: "site";
+    pageScopeId: number;
+} | {
+    kind: "module";
+    ownerModuleId: string;
+    presetKey: string;
+};
+export type PhiPageReference = string & {
+    readonly __phiPageReference: unique symbol;
+};
+export type PhiInternalReference = {
+    kind: "page";
+    reference: PhiPageReference;
+    target: PhiPageTarget;
+    fragment: string | null;
+} | {
+    kind: "asset";
+    assetId: number;
+};
+export declare function createPhiPageReference(target: PhiPageTargetInput): PhiPageReference;
+export declare function readPhiPageReference(value: unknown): {
+    reference: PhiPageReference;
+    target: PhiPageTarget;
+} | null;
+export declare function createPhiPageUri(reference: PhiPageReference, fragment?: string | null): string;
+export declare function createPhiAssetUri(assetId: number): string;
+export declare function readPhiInternalReference(value: unknown): PhiInternalReference | null;
+/**
+ * Where a Control that offers one link leads.
+ *
+ * Two kinds and no third. A Page is named by its reference, which is identity and outlives the path
+ * moving under it; everything else is a literal URL somebody typed. What this refuses is the middle --
+ * the root-relative string that reads as external and means internal -- because that is the shape that
+ * rots in silence: the Page moves, the string does not, and nothing in the system ever knew the two were
+ * related.
+ *
+ * `newTab` sits inside the target rather than beside it. A Widget that offers two links -- a Card with a
+ * heading and an action -- otherwise grows one flag per link and names them in parallel (`newTab`,
+ * `actionNewTab`, and a third the day a third link lands). That is one decision written twice, and it
+ * drifts the first time only one of the two is read.
+ */
+export type PhiLinkTarget = {
+    kind: "page";
+    reference: PhiPageReference;
+    /**
+     * Which Area to resolve the reference in, where it is not the one asking.
+     *
+     * A reference names a Page and not where to look for it: the Area is resolution context, supplied
+     * by whoever asks. Every asker supplied its own, so a link out of one Area into another resolved
+     * to nothing -- the Navigation source tree let an author pick a Page from another Area, the drop
+     * kept it, and the table then showed it as unresolvable.
+     *
+     * Absent means the asking Area, which is nearly every link, so nothing is stored for the ordinary
+     * case. Present, it does not make the reference mean something else; it says where the question
+     * goes. Whether the reader may follow it is still the target Area's own answer.
+     */
+    area?: PhiCmsAreaKey;
+    fragment?: string | null;
+    newTab?: boolean;
+} | {
+    kind: "external";
+    href: string;
+    newTab?: boolean;
+};
+/**
+ * The field names a stored link target may stand under, and nothing else identifies one in persisted
+ * config.
+ *
+ * The Asset rule is the precedent and the reason: the server's reference collector reads persisted JSON,
+ * not the Widget catalogue, so it cannot ask a plugin which of its fields hold targets. A Widget that
+ * keeps one under another name authors a reference the delete guard cannot see, and the Page it points
+ * at can be removed while the Widget still draws a link to it.
+ *
+ * One plain name for the single-link case and a suffix for the rest, so a Card's second link is
+ * `actionLinkTarget` and is found by the same rule that finds the first.
+ */
+export declare const PHI_LINK_TARGET_CONFIG_KEY = "linkTarget";
+export declare function isPhiLinkTargetConfigKey(key: string): boolean;
+export declare function isPhiStorableExternalHref(value: string): boolean;
+/**
+ * A stored link target, read back under the contract rather than trusted.
+ *
+ * Anything that is not one of the two shapes answers `null`, and a Control that gets `null` draws no
+ * link at all. That is the same answer the contract gives for a Page reference that no longer resolves:
+ * non-interactive text beats a link that goes somewhere nobody chose.
+ */
+export declare function readPhiLinkTarget(value: unknown): PhiLinkTarget | null;

package/dist/references.js

@@ -0,0 +1,208 @@
+/**
+ * What one side of the house means when it points at a Page: `@phis/server/references:v1`.
+ *
+ * The codec stood in two copies, in phis-ui and in phi-server, for the same reason the CMS instance id
+ * did before it moved here -- and with the same risk, which is that two sides agreeing byte for byte is
+ * a thing nobody notices stopping. It is one file now.
+ *
+ * **A reference is short because a Page already has a name.** It used to be base64-encoded JSON carrying
+ * the whole identity, which for a Module Page ran to 98 characters in every Markdown body that linked to
+ * one. The envelope was never protection -- it is encoding, not a signature, and the server revalidates
+ * Site and Area regardless -- so what it actually bought was a payload the server could unpack. It no
+ * longer needs to: a Module Page is named by the CMS Page id derived from `(ownerModuleId, presetKey)`,
+ * which is recomputable rather than allocated and therefore stands before any row does.
+ *
+ * The two variants are shaped differently on purpose. A Site Page carries its Page Scope id as a plain
+ * number because the server writes that number into a foreign key with `ON DELETE RESTRICT`: the
+ * database itself refuses to delete a Page something still points at, and nothing derived could take
+ * that column's place. A Module Page has no row to point a foreign key at -- the Site may never have
+ * touched it -- so it carries the derived id, which the server passes on without ever unpacking.
+ */
+import { createPhiPresetCmsInstanceId, isPhiCmsAreaKey, readPhiCmsInstanceIdDescriptor, } from "./cms.js";
+export const PHIS_INTERNAL_PAGE_SCHEME = "phis:page/";
+export const PHIS_INTERNAL_ASSET_SCHEME = "phis:asset/";
+/** The Page itself, not a node inside it -- the one place a Page id differs from a node id. */
+const PHI_CMS_PAGE_NODE_KEY = "page";
+const PHI_PAGE_REFERENCE_VERSION = "v1";
+const PHI_PAGE_REFERENCE_SITE_TAG = "s";
+const PHI_PAGE_REFERENCE_MODULE_TAG = "p";
+const PHI_MODULE_ID_PATTERN = /^@[^/]+\/[^/]+(?:\/[^/]+)*$/;
+const PHI_PAGE_SCOPE_ID_PATTERN = /^[1-9]\d*$/u;
+/**
+ * A Module Page's identity, hashed to one token both sides can recompute.
+ *
+ * Recomputable rather than allocated, so no row has to exist before the Page can be addressed, and it
+ * never mentions the path: reassigning where a Page answers leaves everything pointing at it alone.
+ */
+export function createPhiPresetCmsPageId(identity) {
+    return createPhiPresetCmsInstanceId({
+        ...identity,
+        domain: "page",
+        nodeKey: PHI_CMS_PAGE_NODE_KEY,
+    });
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function readPresetPageId(value) {
+    const descriptor = readPhiCmsInstanceIdDescriptor(value);
+    return descriptor?.origin === "preset" && descriptor.domain === "page"
+        ? value
+        : null;
+}
+export function createPhiPageReference(target) {
+    if (target.kind === "site") {
+        if (!isPositiveInteger(target.pageScopeId)) {
+            throw new Error("Phi Page Scope ids must be positive integers.");
+        }
+        return `${PHI_PAGE_REFERENCE_VERSION}${PHI_PAGE_REFERENCE_SITE_TAG}${target.pageScopeId}`;
+    }
+    /*
+     * Checked here rather than left to the hash. A malformed owner id hashes perfectly well and produces
+     * a reference that resolves to nothing, for a reason nobody can read back out of it -- the one real
+     * cost of a one-way id, paid once at the only place that can still see what went in.
+     */
+    if (!PHI_MODULE_ID_PATTERN.test(target.ownerModuleId.trim())) {
+        throw new Error("Invalid Phi Module id.");
+    }
+    const pageId = createPhiPresetCmsPageId({
+        ownerModuleId: target.ownerModuleId,
+        presetKey: target.presetKey,
+    });
+    return `${PHI_PAGE_REFERENCE_VERSION}${PHI_PAGE_REFERENCE_MODULE_TAG}${pageId}`;
+}
+export function readPhiPageReference(value) {
+    if (typeof value !== "string" || !value.startsWith(PHI_PAGE_REFERENCE_VERSION)) {
+        return null;
+    }
+    const tag = value.slice(PHI_PAGE_REFERENCE_VERSION.length, PHI_PAGE_REFERENCE_VERSION.length + 1);
+    const body = value.slice(PHI_PAGE_REFERENCE_VERSION.length + 1);
+    if (tag === PHI_PAGE_REFERENCE_SITE_TAG) {
+        const pageScopeId = PHI_PAGE_SCOPE_ID_PATTERN.test(body) ? Number(body) : NaN;
+        return isPositiveInteger(pageScopeId)
+            ? { reference: value, target: { kind: "site", pageScopeId } }
+            : null;
+    }
+    if (tag === PHI_PAGE_REFERENCE_MODULE_TAG) {
+        const pageId = readPresetPageId(body);
+        return pageId
+            ? { reference: value, target: { kind: "module", pageId } }
+            : null;
+    }
+    return null;
+}
+export function createPhiPageUri(reference, fragment) {
+    if (!readPhiPageReference(reference)) {
+        throw new Error("Invalid Phi Page reference.");
+    }
+    const normalizedFragment = fragment?.replace(/^#/u, "").trim();
+    return `${PHIS_INTERNAL_PAGE_SCHEME}${reference}${normalizedFragment ? `#${encodeURIComponent(normalizedFragment)}` : ""}`;
+}
+export function createPhiAssetUri(assetId) {
+    if (!isPositiveInteger(assetId)) {
+        throw new Error("Phi Asset ids must be positive integers.");
+    }
+    return `${PHIS_INTERNAL_ASSET_SCHEME}${assetId}`;
+}
+export function readPhiInternalReference(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    if (value.startsWith(PHIS_INTERNAL_ASSET_SCHEME)) {
+        const id = value.slice(PHIS_INTERNAL_ASSET_SCHEME.length);
+        return /^[1-9]\d*$/u.test(id) && Number.isSafeInteger(Number(id))
+            ? { kind: "asset", assetId: Number(id) }
+            : null;
+    }
+    if (!value.startsWith(PHIS_INTERNAL_PAGE_SCHEME)) {
+        return null;
+    }
+    const [encodedReference, ...fragmentParts] = value.slice(PHIS_INTERNAL_PAGE_SCHEME.length).split("#");
+    const parsed = readPhiPageReference(encodedReference);
+    if (!parsed) {
+        return null;
+    }
+    try {
+        const fragment = fragmentParts.length > 0 ? decodeURIComponent(fragmentParts.join("#")) : null;
+        return { kind: "page", ...parsed, fragment };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The field names a stored link target may stand under, and nothing else identifies one in persisted
+ * config.
+ *
+ * The Asset rule is the precedent and the reason: the server's reference collector reads persisted JSON,
+ * not the Widget catalogue, so it cannot ask a plugin which of its fields hold targets. A Widget that
+ * keeps one under another name authors a reference the delete guard cannot see, and the Page it points
+ * at can be removed while the Widget still draws a link to it.
+ *
+ * One plain name for the single-link case and a suffix for the rest, so a Card's second link is
+ * `actionLinkTarget` and is found by the same rule that finds the first.
+ */
+export const PHI_LINK_TARGET_CONFIG_KEY = "linkTarget";
+const PHI_LINK_TARGET_CONFIG_KEY_SUFFIX = "LinkTarget";
+export function isPhiLinkTargetConfigKey(key) {
+    return key === PHI_LINK_TARGET_CONFIG_KEY
+        || (key.endsWith(PHI_LINK_TARGET_CONFIG_KEY_SUFFIX) && key.length > PHI_LINK_TARGET_CONFIG_KEY_SUFFIX.length);
+}
+/**
+ * Whether a string may be kept as an external target.
+ *
+ * Absolute, or an anchor on the document the reader already has. Everything else is refused, and the
+ * refusal is the whole point rather than strictness for its own sake: a stored `/pricing` is a Page link
+ * that has thrown its identity away, and one of them is enough to give the Site a second internal format
+ * -- one the resolver cannot resolve, the index cannot see, and the delete guard cannot warn about.
+ *
+ * The reserved scheme is rejected here in its plain form only. Normalising the encodings it can hide in
+ * belongs to the server's sanitizer, which sees the whole document; this is the near guard, so a target
+ * never carries an unresolved `phis:` URI in the field where a literal URL belongs.
+ */
+const PHI_STORABLE_EXTERNAL_HREF_PATTERN = /^(?:https?:\/\/|\/\/|mailto:|tel:|#)/iu;
+export function isPhiStorableExternalHref(value) {
+    const trimmed = value.trim();
+    return trimmed.length > 0
+        && !trimmed.toLowerCase().startsWith("phis:")
+        && PHI_STORABLE_EXTERNAL_HREF_PATTERN.test(trimmed);
+}
+/**
+ * A stored link target, read back under the contract rather than trusted.
+ *
+ * Anything that is not one of the two shapes answers `null`, and a Control that gets `null` draws no
+ * link at all. That is the same answer the contract gives for a Page reference that no longer resolves:
+ * non-interactive text beats a link that goes somewhere nobody chose.
+ */
+export function readPhiLinkTarget(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const newTab = record.newTab === true ? { newTab: true } : {};
+    if (record.kind === "page") {
+        const parsed = readPhiPageReference(record.reference);
+        if (!parsed) {
+            return null;
+        }
+        const fragment = typeof record.fragment === "string" ? record.fragment.replace(/^#/u, "").trim() : "";
+        /*
+         * An Area that is not one is dropped rather than kept: the alternative is a stored value that asks
+         * a question nowhere can answer, and a link drawing nothing with no way to see why. Falling back to
+         * the asking Area is the behaviour of every link that names none, which is the honest default.
+         */
+        const area = isPhiCmsAreaKey(record.area) ? { area: record.area } : {};
+        return {
+            kind: "page",
+            reference: parsed.reference,
+            ...area,
+            ...(fragment ? { fragment } : {}),
+            ...newTab,
+        };
+    }
+    if (record.kind === "external") {
+        const href = typeof record.href === "string" ? record.href.trim() : "";
+        return isPhiStorableExternalHref(href) ? { kind: "external", href, ...newTab } : null;
+    }
+    return null;
+}

package/dist/resource-links.d.ts

@@ -0,0 +1,94 @@
+/**
+ * References from a Phi record to something in another system: `@phis/server/resource-links:v1`.
+ *
+ * A ticket that is also a GitHub issue, a task that is also a pull request, a thread that is also a
+ * conversation somewhere else. The reference is a row of its own rather than a column on the record,
+ * because a record may have several at once, across several systems, and a column per system is a
+ * schema change per integration.
+ *
+ * The provider is the Add-on that wrote the link, and it is the whole of the ownership rule: an Add-on
+ * reads and writes its own links and sees no others. Two integrations pointing at one ticket therefore
+ * do not have to know about each other, and removing one takes its references with it.
+ *
+ * The link is also what an Add-on's actorless access is made of. A person who can see a record writes
+ * the link; from then on the Add-on may read and append to the conversation that record carries, and
+ * nothing beyond it. Unlinking ends that -- which is why `Synced` is stated per link rather than
+ * assumed: a reference that is only a pointer should not become a standing permission.
+ */
+/** What a link points away from. */
+export type PhisResourceLinkSubject = {
+    kind: "thread";
+    id: number;
+} | {
+    kind: "ticket";
+    id: number;
+} | {
+    kind: "ticketTask";
+    id: number;
+};
+/** What is true of a link, as bit flags. */
+export declare const PhisResourceLinkFlag: {
+    /**
+     * The two sides are kept in step, and this Add-on may reach the subject's thread without an actor.
+     *
+     * A link without it is a reference someone recorded: it is shown, it is followed, and it grants
+     * nothing.
+     */
+    readonly Synced: number;
+};
+/**
+ * One reference, as Core stores it.
+ *
+ * `type` and `state` are the provider's own vocabulary -- an issue, a pull request, open, merged -- and
+ * Core never interprets either. It stores them, indexes the external id against them, and hands them
+ * back; what `21` means is the Add-on's business, exactly as a role name is.
+ */
+export type PhisResourceLink = {
+    id: number;
+    subject: PhisResourceLinkSubject;
+    type: number;
+    externalId: string;
+    url: string | null;
+    state: number | null;
+    flags: number;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * The resource links capability: `@phis/server/resource-links:v1`.
+ *
+ * Bounded twice: to this Add-on's own links, and to subjects the acting user may reach. Writing needs
+ * an actor -- a link is a person saying these two things belong together, and it is what later lets the
+ * Add-on act with no person there. A hook or a job may read the links it wrote and may not make new
+ * ones.
+ */
+export type PhisResourceLinksCapabilityV1 = {
+    /** This Add-on's links on one subject, or none where the subject is out of reach. */
+    list(subject: PhisResourceLinkSubject): Promise<PhisResourceLink[]>;
+    /**
+     * Records a reference, or hands back the one that is already there.
+     *
+     * Asking twice is how an id is learned, the way a declared group is: `(type, externalId)` is unique
+     * within this Add-on and this Site, so a second call answers with the first link instead of failing.
+     */
+    link(input: {
+        subject: PhisResourceLinkSubject;
+        type: number;
+        externalId: string;
+        url?: string | null;
+        state?: number | null;
+        flags?: number;
+    }): Promise<PhisResourceLink>;
+    /** Moves a link's provider-local state. */
+    setState(input: {
+        linkId: number;
+        state: number | null;
+    }): Promise<boolean>;
+    /** Removes a link, and with it whatever actorless reach it granted. */
+    unlink(linkId: number): Promise<boolean>;
+    /** One link of this Add-on by the external id it recorded, or null. */
+    findByExternalId(input: {
+        type: number;
+        externalId: string;
+    }): Promise<PhisResourceLink | null>;
+};

package/dist/resource-links.js

@@ -0,0 +1,27 @@
+/**
+ * References from a Phi record to something in another system: `@phis/server/resource-links:v1`.
+ *
+ * A ticket that is also a GitHub issue, a task that is also a pull request, a thread that is also a
+ * conversation somewhere else. The reference is a row of its own rather than a column on the record,
+ * because a record may have several at once, across several systems, and a column per system is a
+ * schema change per integration.
+ *
+ * The provider is the Add-on that wrote the link, and it is the whole of the ownership rule: an Add-on
+ * reads and writes its own links and sees no others. Two integrations pointing at one ticket therefore
+ * do not have to know about each other, and removing one takes its references with it.
+ *
+ * The link is also what an Add-on's actorless access is made of. A person who can see a record writes
+ * the link; from then on the Add-on may read and append to the conversation that record carries, and
+ * nothing beyond it. Unlinking ends that -- which is why `Synced` is stated per link rather than
+ * assumed: a reference that is only a pointer should not become a standing permission.
+ */
+/** What is true of a link, as bit flags. */
+export const PhisResourceLinkFlag = {
+    /**
+     * The two sides are kept in step, and this Add-on may reach the subject's thread without an actor.
+     *
+     * A link without it is a reference someone recorded: it is shown, it is followed, and it grants
+     * nothing.
+     */
+    Synced: 1 << 0,
+};

package/dist/signals.d.ts

@@ -78,6 +78,7 @@ export declare function isPhiSignalAddressSegment(value: string): boolean;
  */
 export declare function isPhiControllerPluginKey(value: string): boolean;
 export declare function isPhiControllerSignalAddress(address: unknown): address is PhiControllerSignalAddress;
+export declare function readPhiControllerSignalAddress(value: unknown): PhiControllerSignalAddress | undefined;
 /** The instance a `cms:` address names, or null when the string is not one. */
 export declare function readPhiCmsSignalAddressInstanceId(address: string): PhiCmsInstanceId | null;
 export declare function isPhiRegionSignalAddress(address: string): boolean;

package/dist/signals.js

@@ -146,6 +146,9 @@ export function isPhiControllerSignalAddress(address) {
         isPhiSignalAddressSegment(namespacedType.slice(controllerSeparatorIndex + 1)) &&
         isPhiSignalAddressSegment(instanceKey));
 }
+export function readPhiControllerSignalAddress(value) {
+    return isPhiControllerSignalAddress(value) ? value.trim() : undefined;
+}
 /** The instance a `cms:` address names, or null when the string is not one. */
 export function readPhiCmsSignalAddressInstanceId(address) {
     if (!address.startsWith("cms:")) {

package/dist/site-groups.d.ts

@@ -36,3 +36,18 @@ export declare const PHI_GROUP_MEMBERSHIP_LEVELS: readonly [1, number, number, n
  * Reading downwards is what makes an unknown higher bit fail closed rather than round up.
  */
 export declare function readPhiGroupMembershipLevel(value: unknown): PhiGroupMembershipFlagValue | null;
+/**
+ * A group a Module needs the Site to have, named rather than created.
+ *
+ * It travels in a Module's `seed` and is written when the Area carrying that Module is published. The
+ * key is the Module's own and never changes: it is what makes a second publish find the group it made
+ * the first time instead of making another. `provider_id` is the Module's id and is supplied by the
+ * materialization, not by the declaration, so a Module cannot claim a group belonging to another.
+ *
+ * The name is a starting value. Once the row exists it is the Site's, and administration renames it
+ * without the next publish undoing that.
+ */
+export type PhisDeclaredSiteGroup = {
+    readonly key: string;
+    readonly name: string;
+};