@phis/contracts 0.4.0 → 0.6.0

package/dist/references.js

@@ -0,0 +1,241 @@
+/**
+ * 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.
+ */
+const PHI_ROUTE_PARAM_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/u;
+/** Route parameter values as a target stores them: names a route can declare, non-empty string values. */
+function readPhiRouteParams(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const entries = Object.entries(value).flatMap(([name, entry]) => PHI_ROUTE_PARAM_NAME_PATTERN.test(name) && typeof entry === "string" && entry.trim()
+        ? [[name, entry.trim()]]
+        : []);
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+/**
+ * A route pattern with its parameters filled, or `null` while one is still open.
+ *
+ * Each value is one path segment, encoded as one: a slug with a slash in it cannot step into another
+ * route. A pattern without parameters comes back as it is.
+ */
+export function fillPhiRouteParams(pattern, params) {
+    let open = false;
+    const filled = pattern.split("/").map((segment) => {
+        if (!segment.startsWith(":"))
+            return segment;
+        const value = params?.[segment.slice(1)];
+        if (!value) {
+            open = true;
+            return segment;
+        }
+        return encodeURIComponent(value);
+    }).join("/");
+    return open ? null : filled;
+}
+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 } : {};
+        const params = readPhiRouteParams(record.params);
+        return {
+            kind: "page",
+            reference: parsed.reference,
+            ...area,
+            ...(params ? { params } : {}),
+            ...(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

@@ -59,8 +59,9 @@ export type PhisResourceLink = {
  *
  * 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.
+ * Add-on act with no person there. A hook or a job may read the links it wrote and may make new ones only
+ * on what it opened itself: a thread it owns -- or a ticket or task whose thread it owns -- it reaches
+ * already, so a link there grants nothing that needed anybody's consent.
  */
 export type PhisResourceLinksCapabilityV1 = {
     /** This Add-on's links on one subject, or none where the subject is out of reach. */
@@ -68,8 +69,10 @@ export type PhisResourceLinksCapabilityV1 = {
     /**
      * 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.
+     * Asking twice is how an id is learned, the way a declared group is: `(subject, type, externalId)` is
+     * unique within this Add-on and this Site, so a second call for the same subject answers with the first
+     * link instead of failing. One external record may be linked from several subjects -- one issue that
+     * several tickets wait on -- and each of those links is its own.
      */
     link(input: {
         subject: PhisResourceLinkSubject;
@@ -86,9 +89,12 @@ export type PhisResourceLinksCapabilityV1 = {
     }): 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: {
+    /**
+     * Every link of this Add-on to one external record, oldest first: what an event about that record has
+     * to reach. Empty where none is recorded.
+     */
+    listByExternalId(input: {
         type: number;
         externalId: string;
-    }): Promise<PhisResourceLink | null>;
+    }): Promise<PhisResourceLink[]>;
 };

package/dist/schema.d.ts

@@ -235,6 +235,15 @@ export type PhisAddonAssetSlotDescriptor = {
      * newest of several would be a fact nobody asked for.
      */
     mirrorColumn?: string;
+    /**
+     * A role this Add-on declares, which the actor must hold to put a file in this slot, take one out,
+     * or list what it holds -- the same guard `requiresRole` is on a declared query, refused loudly.
+     *
+     * On an owner- or group-scoped table it narrows: the row's own authority still has to agree. On a
+     * table with neither, Core has no row to judge, so a slot there must state one, and the role is then
+     * the whole authority -- which is what lets a category icon or a shop logo carry a file at all.
+     */
+    requiresRole?: string;
 };
 export type PhisAddonTableDescriptor = {
     name: string;

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/support.d.ts

@@ -1,3 +1,4 @@
+import type { PhisSecretsCapabilityV1, PhisSettingsCapabilityV1 } from "./capabilities.js";
 /**
  * The Support vocabulary Core and the Support Module must spell the same way.
  *
@@ -44,6 +45,17 @@ export declare const PhisSupportTicketTypeFlag: {
      */
     readonly Requestable: number;
 };
+/**
+ * What is true of one ticket, as bit flags (`support_tickets.flags`).
+ *
+ * `AwaitingDelivery`: the work is resolved and the fix is not in the requester's hands yet. An integration
+ * that tracks releases sets it when the merge resolves the ticket, and the requester window does not start
+ * until the release says the fix is out (`delivered_at`): a window that ran out before anybody could have
+ * the fix would close a ticket nobody had a chance to object to.
+ */
+export declare const PhisSupportTicketFlag: {
+    readonly AwaitingDelivery: number;
+};
 /**
  * What is true of a Support queue, as bit flags.
  *
@@ -327,6 +339,13 @@ export type PhisSupportCapabilityV1 = {
     }): Promise<PhisSupportTicket>;
     /** The work on one ticket, in the order the Site keeps it. */
     listTasks(ticketId: number): Promise<PhisSupportTicketTask[]>;
+    /**
+     * One task, or null where its ticket is out of reach or it is absent.
+     *
+     * The way back from a link: an integration that hears about its external record finds the link, the
+     * link names a task, and the task names its ticket -- whose conversation a comment belongs in.
+     */
+    getTask(taskId: number): Promise<PhisSupportTicketTask | null>;
     /** Records a piece of work, which is what a linked issue hangs on. */
     addTask(input: {
         ticketId: number;
@@ -339,6 +358,19 @@ export type PhisSupportCapabilityV1 = {
         taskId: number;
         status: number;
     }): Promise<PhisSupportTicketTask>;
+    /**
+     * Holds a resolved ticket's requester window until the fix is delivered.
+     *
+     * For an integration that tracks releases: the merge resolved the ticket, and the requester cannot have
+     * the fix until a release carries it. False where the ticket is not resolved -- there is no window to
+     * hold. Reopening or resolving again lets go of it.
+     */
+    awaitDelivery(ticketId: number): Promise<boolean>;
+    /**
+     * Says the fix is out: the requester window of a resolved ticket starts now. False where the ticket is
+     * not resolved or was already delivered.
+     */
+    markDelivered(ticketId: number): Promise<boolean>;
     /**
      * What one person may still ask for, of one type.
      *
@@ -388,3 +420,155 @@ export type PhisSupportCapabilityV1 = {
         reference: string;
     }): Promise<PhisSupportAllowanceGrant | null>;
 };
+/**
+ * What Core hands an implementation of `@phis/server/service/support-forwarding` when it builds one.
+ *
+ * Built per Site and per forward, so the context names the Site; what the implementation talks to and how
+ * it signs in is its own, which is why what it reads from Core is its own configuration and nothing else.
+ */
+export type PhisSupportForwardingServiceContext = {
+    /** The Add-on implementing the kind. */
+    providerId: string;
+    siteKey: string;
+    /**
+     * The implementation's own Site secrets and settings, the same two capabilities its hooks and jobs
+     * have: where the work goes (a repository, an installation) is per-Site configuration, and so are the
+     * credentials it goes with.
+     */
+    secrets: PhisSecretsCapabilityV1;
+    settings: PhisSettingsCapabilityV1;
+};
+/**
+ * One place an implementation can send work to: a repository, a project, a desk.
+ *
+ * `key` is the implementation's own name for it and comes back unchanged in `PhisSupportForwardRequest`;
+ * `label` is shown to a Supporter as it is ("GitHub acme/app").
+ */
+export type PhisSupportForwardingTarget = {
+    key: string;
+    label: string;
+};
+/**
+ * Whether this implementation can take work on this Site right now, and where.
+ *
+ * Asked before a Supporter is offered anything. One implementation may offer several targets -- every
+ * repository its installation reaches, say -- and a Supporter chooses one per forward. `findings` say in an
+ * operator's terms what does not answer when `usable` is false or a target is left out.
+ */
+export type PhisSupportForwardingProbe = {
+    usable: boolean;
+    targets: PhisSupportForwardingTarget[];
+    findings: string[];
+};
+/**
+ * One ticket's work, handed over.
+ *
+ * `mirror` is the ticket type's `External`, decided by Core and not by the implementation: where it is
+ * false the external record is opened from the title alone and nothing of the conversation follows it.
+ * Where it is true, `body` is what opens it -- the ticket's first message, and only if the person who
+ * wrote it agreed to it leaving the Site. What follows afterwards reaches the implementation as thread
+ * events, through the synced link Core writes for it, and Core withholds there what may not leave.
+ */
+export type PhisSupportForwardRequest = {
+    /** The target the Supporter chose, by the key the probe gave it. */
+    target: string;
+    ticket: {
+        id: number;
+        threadId: number;
+        subject: string;
+        typeKey: string;
+    };
+    task: {
+        title: string;
+    };
+    mirror: boolean;
+    body: string | null;
+    /** Who forwarded it, for the external record's attribution. */
+    actor: {
+        userId: number;
+        displayName: string | null;
+    };
+    signal: AbortSignal;
+};
+/**
+ * The external record the work now lives in.
+ *
+ * `type` and `state` are the implementation's own vocabulary -- an issue, a pull request, open -- and Core
+ * stores them on the resource link it writes for the forward without interpreting either, as it does for
+ * every link.
+ */
+export type PhisSupportForwardResult = {
+    type: number;
+    externalId: string;
+    url: string | null;
+    state: number | null;
+};
+/**
+ * A record that already exists in the other system, named by a Supporter: what they pasted, as it is.
+ *
+ * `reference` is whatever the implementation's own people call one -- a URL, `owner/name#12` -- and each
+ * implementation reads only its own. Looking one up changes nothing anywhere: whether the link is made is
+ * Core's to decide afterwards, and the record hears of it only once it stands (`linked`).
+ */
+export type PhisSupportLinkLookup = {
+    reference: string;
+    signal: AbortSignal;
+};
+/**
+ * What an implementation answers about a reference.
+ *
+ * - `unknown`: not one of its own; Core asks the next implementation.
+ * - `refused`: its own, but no work can go there -- closed, out of the Site's reach, gone. `reason` is
+ *   shown to the Supporter as it is.
+ * - `linkable`: the record, as `forward` would have answered it, and what it is called there, which
+ *   becomes the engineering task's title.
+ */
+export type PhisSupportLinkResult = {
+    status: "unknown";
+} | {
+    status: "refused";
+    reason: string;
+} | {
+    status: "linkable";
+    record: PhisSupportForwardResult;
+    title: string;
+};
+/**
+ * A link that now stands, so the record can say where it is linked from, as a forwarded one does in its
+ * body. Nothing of the conversation travels with it: a link hands nothing over by itself.
+ */
+export type PhisSupportLinkedNotice = {
+    record: PhisSupportForwardResult;
+    ticket: {
+        id: number;
+        threadId: number;
+        subject: string;
+        typeKey: string;
+    };
+    /** Who linked it, for the record's attribution. */
+    actor: {
+        userId: number;
+        displayName: string | null;
+    };
+    signal: AbortSignal;
+};
+/**
+ * The interface of `@phis/server/service/support-forwarding`, version 1.
+ *
+ * Whether it can take work, taking it, and linking work that is already there -- an issue somebody opened
+ * in the other system before or beside the ticket: `lookup` says what a reference is, Core records the link,
+ * and `linked` tells the record. A linked record is followed exactly as a forwarded one is; only how it
+ * came to exist differs, and a `linked` that fails leaves the link standing.
+ *
+ * Everything after the hand-over is the capabilities every Add-on has -- `support:v1` to finish the engineering task the forward created,
+ * `threads:v1` to answer in the conversation, `resource-links:v1` to move the link's state -- so that what
+ * happens to a ticket stays Core's to decide.
+ */
+export interface PhisSupportForwardingAdapterV1 {
+    probe(input: {
+        signal: AbortSignal;
+    }): Promise<PhisSupportForwardingProbe>;
+    forward(input: PhisSupportForwardRequest): Promise<PhisSupportForwardResult>;
+    lookup(input: PhisSupportLinkLookup): Promise<PhisSupportLinkResult>;
+    linked(input: PhisSupportLinkedNotice): Promise<void>;
+}

package/dist/support.js

@@ -44,6 +44,17 @@ export const PhisSupportTicketTypeFlag = {
      */
     Requestable: 1 << 2,
 };
+/**
+ * What is true of one ticket, as bit flags (`support_tickets.flags`).
+ *
+ * `AwaitingDelivery`: the work is resolved and the fix is not in the requester's hands yet. An integration
+ * that tracks releases sets it when the merge resolves the ticket, and the requester window does not start
+ * until the release says the fix is out (`delivered_at`): a window that ran out before anybody could have
+ * the fix would close a ticket nobody had a chance to object to.
+ */
+export const PhisSupportTicketFlag = {
+    AwaitingDelivery: 1 << 0,
+};
 /**
  * What is true of a Support queue, as bit flags.
  *

package/dist/threads.d.ts

@@ -278,6 +278,11 @@ export type PhisThreadsCapabilityV1 = {
      *
      * `messageFlags` is normalized rather than trusted: `Internal` requires an actor who is Staff, and
      * `Imported` is Core's to set on what arrives through an integration.
+     *
+     * One exception, and only in the narrowing direction: without an actor, an Add-on may mark a message it
+     * imports -- one carrying `externalRef` -- as `Internal`. What it brings in from outside is its own to
+     * keep from the requester, as a maintainer's comment on an issue is; nothing it writes can be made
+     * readable to more people this way, only to fewer.
      */
     create(input: {
         kind: PhisThreadKindValue;
@@ -321,6 +326,7 @@ export type PhisThreadsCapabilityV1 = {
      *
      * Idempotent on `externalRef` where one is given: the same reference answers with the thread as it
      * stands instead of writing a second message, which is what a webhook delivered twice needs.
+     * `messageFlags` follow the terms `create` states, its exception for an imported `Internal` included.
      */
     reply(input: {
         threadId: number;
@@ -360,4 +366,27 @@ export type PhisThreadsCapabilityV1 = {
      * or `reply`, so it finds its way back to a conversation it already knows about and to no other.
      */
     findByExternalRef(externalRef: string): Promise<PhisThreadDetail | null>;
+    /**
+     * Records that a message of a reachable thread was written out to the other system, under that
+     * system's id for it. True when recorded now, false when it already was -- an event delivered twice
+     * finds its first export and posts nothing.
+     *
+     * An exported message is never imported back: what this Add-on wrote out and then hears about again is
+     * recognised by the reference and left alone.
+     */
+    recordExport(input: {
+        messageId: number;
+        externalRef: string;
+    }): Promise<boolean>;
+    /** The other system's id for a message this Add-on exported, or null. */
+    findExport(messageId: number): Promise<string | null>;
+    /**
+     * Changes a message this Add-on imported, as its source changed it: new text marks it `Edited`, `null`
+     * withdraws it -- the text is gone and the message stays, `Redacted`, so the conversation still reads.
+     * False where this Add-on imported nothing under that reference.
+     */
+    amendImported(input: {
+        externalRef: string;
+        message: string | null;
+    }): Promise<boolean>;
 };

package/dist/timeline.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a Timeline shows, the same for a Widget's own entries and for a Timeline Provider's answer.
+ *
+ * A Provider may run in a Module of ours, in an outside Module, or answer from an Add-on behind a Site
+ * route, so the entry is spelled here rather than in the UI package: every end that hands entries over
+ * reads and writes this shape.
+ */
+/** What an entry's mark says about it: a word about meaning, so the Theme decides the colour. */
+export declare const PHI_TIMELINE_TONES: readonly ["secondary", "success", "warning", "danger"];
+export type PhiTimelineTone = (typeof PHI_TIMELINE_TONES)[number];
+export type PhiTimelineEntry = {
+    /** Stable within the list; the entry's identity when the list is drawn again. */
+    key: string;
+    title?: string;
+    content: string;
+    /**
+     * When it happened, as an ISO 8601 date or date-time. The Widget formats it for the reader's locale.
+     * An entry that states `time` as well shows `time`.
+     */
+    at?: string;
+    /**
+     * When it happened, already in words: "Spring 2026", "v1.2", "Yesterday". Shown as written, and
+     * preferred over `at` where an entry states both.
+     */
+    time?: string;
+    /** A Phi icon name, drawn in place of the mark. */
+    icon?: string;
+    tone?: PhiTimelineTone;
+    /** Still under way: the mark spins. */
+    pending?: boolean;
+};
+/** A Timeline Provider's answer. */
+export type PhiTimelineProviderResult = {
+    entries: PhiTimelineEntry[];
+};
+export declare function isPhiTimelineTone(value: unknown): value is PhiTimelineTone;
+/** One entry, or `null` for anything that is not one. An entry without a key or text is not one. */
+export declare function readPhiTimelineEntry(value: unknown): PhiTimelineEntry | null;
+export declare function readPhiTimelineEntries(value: unknown): PhiTimelineEntry[];