@phis/contracts 0.5.0 → 0.7.0

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[];

package/dist/timeline.js

@@ -0,0 +1,53 @@
+/**
+ * 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 const PHI_TIMELINE_TONES = ["secondary", "success", "warning", "danger"];
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+export function isPhiTimelineTone(value) {
+    return typeof value === "string" && PHI_TIMELINE_TONES.includes(value);
+}
+/**
+ * The `at` of an entry, when it is a date this reader can place. A string that is not one is dropped
+ * rather than shown: an unreadable instant would print as "Invalid Date" in the reader's language.
+ */
+function readInstant(value) {
+    const text = readString(value);
+    return text && !Number.isNaN(Date.parse(text)) ? text : undefined;
+}
+/** One entry, or `null` for anything that is not one. An entry without a key or text is not one. */
+export function readPhiTimelineEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const key = readString(record.key);
+    if (!key) {
+        return null;
+    }
+    const title = readString(record.title);
+    const at = readInstant(record.at);
+    const time = readString(record.time);
+    const icon = readString(record.icon);
+    return {
+        key,
+        content: typeof record.content === "string" ? record.content : "",
+        ...(title ? { title } : {}),
+        ...(at ? { at } : {}),
+        ...(time ? { time } : {}),
+        ...(icon ? { icon } : {}),
+        ...(isPhiTimelineTone(record.tone) ? { tone: record.tone } : {}),
+        ...(record.pending === true ? { pending: true } : {}),
+    };
+}
+export function readPhiTimelineEntries(value) {
+    return Array.isArray(value)
+        ? value.map(readPhiTimelineEntry).filter((entry) => entry != null)
+        : [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/contracts",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {
@@ -15,6 +15,11 @@
     "prepack": "npm run build"
   },
   "exports": {
+    "./payments": {
+      "types": "./dist/payments.d.ts",
+      "import": "./dist/payments.js",
+      "default": "./dist/payments.js"
+    },
     "./references": {
       "types": "./dist/references.d.ts",
       "import": "./dist/references.js",
@@ -114,6 +119,11 @@
       "types": "./dist/layout.d.ts",
       "import": "./dist/layout.js",
       "default": "./dist/layout.js"
+    },
+    "./timeline": {
+      "types": "./dist/timeline.d.ts",
+      "import": "./dist/timeline.js",
+      "default": "./dist/timeline.js"
     }
   },
   "files": [