@phis/contracts 0.5.0 → 0.6.0

package/README.md

@@ -6,6 +6,7 @@ and change at different moments.
 
 ```
 @phis/contracts/addon                what phis and a separately shipped Add-on promise each other
+@phis/contracts/payments             the approved Payment consumer, Provider and merchant-profile types
 @phis/contracts/access               the authorization vocabulary phis and @phis/ui both evaluate
 @phis/contracts/signals              the signal vocabulary and address grammar the UI declares in and phis validates
 @phis/contracts/catalog              the Module categories an Add-on declares, the UI groups by and a market filters on
@@ -45,7 +46,7 @@ The types and constants an Add-on declares or implements. Types and constants on
 `server-only`, no React, no Next.
 
 An Add-on is compiled to a single ESM artifact and installed into a running phis through the `phis` CLI;
-it is never built into the server. This subpath is the only thing an Add-on compiles against, and it must
+it is never built into the server. This subpath is the shared Add-on entrypoint it compiles against, and it must
 not depend on phis itself. For an Add-on author it is a build-time dependency: everything it exports is
 erased at compile time apart from a handful of constants.
 
@@ -61,10 +62,10 @@ What it covers:
   (`PhisMediaStorageAdapter`, upload plans, object I/O) and Directory. `PHIS_SERVICE_KINDS` names them
   and `PHIS_SERVICE_INTERFACE_DIGESTS` holds the digest of each kind's current interface; Core refuses an
   Add-on built against a different digest at install.
-- **Core capabilities** -- `PHIS_CORE_CAPABILITIES`, the capability ids an Add-on may require. Declare
-  against these constants rather than spelling the ids out. The list is the vocabulary and may reserve a
-  name before Core delivers it (`resource-links`, `support`); an Add-on that requires a capability this
-  release does not deliver is refused rather than handed a missing object.
+- **Core capabilities** -- `PHIS_CORE_CAPABILITIES`, the catalogue ids an Add-on may require. Declare
+  against these constants rather than spelling the ids out. Core separately validates delivery to
+  Add-ons; a catalogue id such as `authentication` may serve Site Modules without a corresponding
+  Add-on context field. Payment ids accompany the implemented Core capability/service/event catalogue.
 
 `PHIS_ADDON_ABI_VERSION` is the single number phis checks an Add-on against.
 
@@ -72,6 +73,23 @@ How an Add-on is laid out, compiled, installed, activated and upgraded is descri
 [`ADDON_HOWTO.md`](https://github.com/phis-dev/phis-server/blob/main/ADDON_HOWTO.md); the rules behind it
 are in [`SERVER_ADDONS.md`](https://github.com/phis-dev/phis-server/blob/main/SERVER_ADDONS.md).
 
+## `/payments`
+
+The approved v1 consumer capability, Provider adapter, checkout plans, normalized money,
+payment/operation/refund records, merchant profile/grant types and owning-consumer event facts.
+All exports are types; there is no secret accessor implementation, checkout SDK, exchange-rate
+conversion or Payment engine here. The same types are re-exported by `/addon`.
+
+Consumers own their prices in CHF, EUR, USD or another supported currency. Every payment uses one
+currency; capture and refunds inherit it. Core never infers conversion or settlement currency.
+
+Core implements Payment execution separately. Its catalogue exports `payments`, `paymentNotifications`,
+the Payment service kind/interface digest and `payment.changed`. Notification ingress is available
+only in a bound hook context. The Add-on event context discriminates thread and Payment subjects;
+thread producers remain explicitly typed as thread events.
+See the normative [Payment contract](https://github.com/phis-dev/phis-server/blob/main/PAYMENTS.md)
+and [Stripe/profile contract](https://github.com/phis-dev/phis-server/blob/main/PAYMENTS_STRIPE.md).
+
 ## `/access`
 
 Claim shapes, policy shapes, and the evaluator that decides them. Unlike `/addon`, this is runtime code

package/dist/addon-index.d.ts

@@ -3,6 +3,7 @@ export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";
+export * from "./payments.js";
 export * from "./queries.js";
 export * from "./resource-links.js";
 export * from "./schema.js";

package/dist/addon-index.js

@@ -3,6 +3,7 @@ export * from "./assets.js";
 export * from "./capabilities.js";
 export * from "./core.js";
 export * from "./media-storage.js";
+export * from "./payments.js";
 export * from "./queries.js";
 export * from "./resource-links.js";
 export * from "./schema.js";

package/dist/addon.d.ts

@@ -65,7 +65,9 @@ export type PhisAddonHookDescriptor = {
      *
      * Absent is not a lesser variant of present: an unverified hook writes nothing at all -- not through
      * `data:v1`, not by opening a thread -- because nothing distinguishes its caller from anybody who
-     * found the address. A hook that needs to write declares how it can be believed.
+     * found the address. A hook that needs ambient write authority declares how it can be believed.
+     * Target v1 Payment notification ingress instead verifies through its bound Core capability and
+     * reconciles Core-owned payment state without granting ambient hook write authority.
      */
     verification?: PhisAddonHookVerificationDescriptor;
     /**

package/dist/capabilities.d.ts

@@ -12,7 +12,8 @@
  * at the point where it made the mistake.
  */
 import type { PhisAssetsCapabilityV1 } from "./assets.js";
-import type { PhisAddonEventId } from "./core.js";
+import type { PhisAddonThreadEventId } from "./core.js";
+import type { PhisPaymentChangedEventFacts, PhisPaymentNotificationsCapabilityV1, PhisPaymentsCapabilityV1 } from "./payments.js";
 import type { PhisDataCapabilityV1 } from "./queries.js";
 import type { PhisResourceLinksCapabilityV1 } from "./resource-links.js";
 import type { PhisSupportCapabilityV1 } from "./support.js";
@@ -102,6 +103,10 @@ export type PhisAddonCapabilities = {
     support?: PhisSupportCapabilityV1;
     settings?: PhisSettingsCapabilityV1;
     roles?: PhisRolesCapabilityV1;
+    /** Bound to the declaring consumer and Site when required. */
+    payments?: PhisPaymentsCapabilityV1;
+    /** Supplied only to an original, bound Payment Provider hook request. */
+    paymentNotifications?: PhisPaymentNotificationsCapabilityV1;
 };
 /**
  * The roles capability: `@phis/server/roles:v1`.
@@ -206,9 +211,19 @@ export type PhisStorageCapabilityV1 = {
  * own would be a package that could plant one.
  */
 export type PhisSecretsCapabilityV1 = {
-    /** The value, or null when the operator has not configured it. */
-    read(name: string): Promise<string | null>;
+    /**
+     * The value, or null when the operator has not configured it.
+     *
+     * `scope` says which of the two an operator can set: `"site"` (the default) is the one set with
+     * `--site` for the Site this call runs on; `"addon"` is the one set without `--site`, shared by every
+     * Site the Add-on runs on -- one credential for one external account, such as a single app
+     * registration. The two are never substituted for each other: a Site secret that is missing is
+     * `null`, not the shared one.
+     */
+    read(name: string, scope?: PhisSecretScope): Promise<string | null>;
 };
+/** Which secret `PhisSecretsCapabilityV1.read` names: the Site's own, or the one shared by all Sites. */
+export type PhisSecretScope = "site" | "addon";
 /**
  * What an Add-on may learn about a person.
  *
@@ -357,24 +372,26 @@ export type PhisAddonJobContext = {
  * this Site something, an event is this Site telling an Add-on something, and both run as the Add-on
  * rather than as a person.
  *
- * Delivery is bounded by the same link. An Add-on is told about a thread it is synced with and about no
- * other, because a Site-wide feed of everything anybody writes is the listing `threads:v1` refuses,
- * arriving by push instead of by pull.
+ * Thread delivery is bounded by a synced link. The Payment event reaches only its stored
+ * consuming Add-on. The subject kind and event discriminate those two ownership models; approved
+ * Payment facts are delivered through Core's durable owner-directed outbox.
  */
-export type PhisAddonEventContext = {
+export type PhisAddonEventFacts = {
+    event: PhisAddonThreadEventId;
+    subject: {
+        kind: "thread";
+        threadId: number;
+        messageId: number | null;
+    };
+} | PhisPaymentChangedEventFacts;
+export type PhisAddonEventContext = PhisAddonEventFacts & {
     addonId: string;
-    event: PhisAddonEventId;
     /** This delivery, stable across retries, so a handler can recognise one it already settled. */
     deliveryId: string;
     site: {
         id: number;
         key: string;
     };
-    /** The thread the event happened in, and the message where the event is about one. */
-    subject: {
-        threadId: number;
-        messageId: number | null;
-    };
     capabilities: PhisAddonCapabilities;
     signal: AbortSignal;
 };

package/dist/cms.d.ts

@@ -73,7 +73,9 @@ export declare const PhiCmsVisibilityContext: {
  * The flags a CMS row carries, in the one numbering both sides read them from.
  *
  * Not every flag reaches every kind of row -- `Collapsed` is a Region's answer and `MobileOnly` a
- * renderable's -- but they share one space, because a row is stored as a row whatever it holds.
+ * renderable's -- but they share one space, because a row is stored as a row whatever it holds. The
+ * same numbering serves a config's own `flags`, where a Region's and an Overlay's behaviour live
+ * (`Sticky`, `NoCloseButton`, ...): a yes-or-no answer in a stored record is a bit, never a boolean.
  *
  * `NoIndex` is a Page's, and it is the Site's answer rather than the preset's: a Module states what a
  * Page it ships starts out as, and the Builder's switch is what decides from then on. That is why it
@@ -88,6 +90,26 @@ export declare const PhiCmsFlags: {
     readonly Collapsed: number;
     readonly NoTranslate: number;
     readonly NoIndex: number;
+    /** Stays in view while the page scrolls (Header and Sider families). */
+    readonly Sticky: number;
+    /** A Sider that takes the viewport height below its offset. */
+    readonly FullHeight: number;
+    /** A Sider the viewer can fold to its collapsed width. */
+    readonly Collapsible: number;
+    /** The Header chrome renders no close button. */
+    readonly NoCloseButton: number;
+    /** Escape does not request dismissal. */
+    readonly NoEscapeClose: number;
+    /** A Modal centred in the viewport. */
+    readonly Centered: number;
+    /** A Drawer the viewer can resize. */
+    readonly Resizable: number;
+    /** A Drawer that pushes a nested Drawer aside (`pushDistance` states how far). */
+    readonly Push: number;
+    /** Pointer input reaches the page behind the Overlay. */
+    readonly MaskPassesPointer: number;
+    /** An outside pointer action does not request dismissal. */
+    readonly MaskKeepsOpen: number;
 };
 export declare const PhiCmsRevisionFlags: {
     readonly Draft: number;

package/dist/cms.js

@@ -81,7 +81,9 @@ export const PhiCmsVisibilityContext = {
  * The flags a CMS row carries, in the one numbering both sides read them from.
  *
  * Not every flag reaches every kind of row -- `Collapsed` is a Region's answer and `MobileOnly` a
- * renderable's -- but they share one space, because a row is stored as a row whatever it holds.
+ * renderable's -- but they share one space, because a row is stored as a row whatever it holds. The
+ * same numbering serves a config's own `flags`, where a Region's and an Overlay's behaviour live
+ * (`Sticky`, `NoCloseButton`, ...): a yes-or-no answer in a stored record is a bit, never a boolean.
  *
  * `NoIndex` is a Page's, and it is the Site's answer rather than the preset's: a Module states what a
  * Page it ships starts out as, and the Builder's switch is what decides from then on. That is why it
@@ -96,6 +98,35 @@ export const PhiCmsFlags = {
     Collapsed: 1 << 4,
     NoTranslate: 1 << 5,
     NoIndex: 1 << 6,
+    /*
+     * A Region's behaviour, carried in its config's `flags`: a Region stored on a Page is a config under
+     * the Page's `layoutConfig` and has no row of its own, so the config is the one place both kinds have.
+     */
+    /** Stays in view while the page scrolls (Header and Sider families). */
+    Sticky: 1 << 7,
+    /** A Sider that takes the viewport height below its offset. */
+    FullHeight: 1 << 8,
+    /** A Sider the viewer can fold to its collapsed width. */
+    Collapsible: 1 << 9,
+    /*
+     * An Overlay's behaviour, carried in its config's `flags` the same way. The bits name the departure
+     * from the Overlay's defaults, so an unset flag set is the plain Overlay: a close button, Escape
+     * closes, the mask stops the pointer and closes on a click.
+     */
+    /** The Header chrome renders no close button. */
+    NoCloseButton: 1 << 10,
+    /** Escape does not request dismissal. */
+    NoEscapeClose: 1 << 11,
+    /** A Modal centred in the viewport. */
+    Centered: 1 << 12,
+    /** A Drawer the viewer can resize. */
+    Resizable: 1 << 13,
+    /** A Drawer that pushes a nested Drawer aside (`pushDistance` states how far). */
+    Push: 1 << 14,
+    /** Pointer input reaches the page behind the Overlay. */
+    MaskPassesPointer: 1 << 15,
+    /** An outside pointer action does not request dismissal. */
+    MaskKeepsOpen: 1 << 16,
 };
 export const PhiCmsRevisionFlags = {
     Draft: 1 << 0,

package/dist/controls.d.ts

@@ -26,7 +26,15 @@ export type PhiControlOption<TValue extends string | number = string> = {
      * come, so the order has to make sense without the headings.
      */
     group?: string;
+    /**
+     * A line drawn between this option and the one before or after it, where the Control can draw one --
+     * a Select does, in its menu. It sets an option apart from the rest without a heading to name it: the
+     * Button's "Custom" above the actions it is not one of. A Control that cannot draw it lists the
+     * options as they come.
+     */
+    separator?: PhiControlOptionSeparator;
 };
+export type PhiControlOptionSeparator = "before" | "after";
 export type PhiControlOptionPreview = PhiControlOptionBackgroundPreview | PhiControlOptionFontPreview;
 /**
  * The option's label set in the typeface it names, so a list of fonts shows the fonts.

package/dist/controls.js

@@ -125,6 +125,7 @@ export function readPhiControlOptions(value) {
                 icon: readString(record.icon),
                 preview: readOptionPreview(record.preview),
                 group: readString(record.group),
+                separator: record.separator === "before" || record.separator === "after" ? record.separator : undefined,
             };
         })
             .filter((item) => item != null);

package/dist/core.d.ts

@@ -1,3 +1,4 @@
+import type { PhisPaymentChangedEventFacts } from "./payments.js";
 /**
  * What Core offers, named once so both sides can spell it the same way.
  *
@@ -45,6 +46,8 @@ export declare const PHIS_CORE_CAPABILITIES: {
     readonly settings: "@phis/server/settings:v1";
     /** Whether the acting user holds one of this Add-on's own declared roles. */
     readonly roles: "@phis/server/roles:v1";
+    readonly payments: "@phis/server/payments:v1";
+    readonly paymentNotifications: "@phis/server/payment-notifications:v1";
 };
 export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof PHIS_CORE_CAPABILITIES];
 /**
@@ -67,8 +70,11 @@ export declare const PHIS_ADDON_EVENTS: {
     readonly threadStatusChanged: "thread.status.changed";
     /** The link itself is gone; what follows from that is the Add-on's own business. */
     readonly threadLinkRemoved: "thread.link.removed";
+    readonly paymentChanged: "payment.changed";
 };
-export type PhisAddonEventId = (typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDON_EVENTS];
+export type PhisAddonThreadEventId = Exclude<(typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDON_EVENTS], "payment.changed">;
+/** Delivered v1 event vocabulary, discriminated by its owned subject. */
+export type PhisAddonEventId = PhisAddonThreadEventId | PhisPaymentChangedEventFacts["event"];
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -78,6 +84,7 @@ export type PhisAddonEventId = (typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDO
  */
 export declare const PHIS_SERVICE_KINDS: {
     readonly mediaStorage: "@phis/server/service/media-storage";
+    readonly payments: "@phis/server/service/payments";
     readonly directory: "@phis/server/service/directory";
     /**
      * Turning text in one language into text in another.
@@ -88,6 +95,15 @@ export declare const PHIS_SERVICE_KINDS: {
      * operator selects which one an installation uses.
      */
     readonly translation: "@phis/server/service/translation";
+    /**
+     * Handing a Support ticket's work to a system outside the Site -- an issue tracker, a ticket desk.
+     *
+     * A kind because Core owns the question: which ticket, which task, what may leave and what comes back.
+     * What the implementation talks to is its own business, and several may be installed at once; a
+     * Supporter chooses one per forward. The interface is `PhisSupportForwardingAdapterV1` in
+     * `@phis/contracts/support`.
+     */
+    readonly supportForwarding: "@phis/server/service/support-forwarding";
 };
 export type PhisServiceKind = (typeof PHIS_SERVICE_KINDS)[keyof typeof PHIS_SERVICE_KINDS];
 /**

package/dist/core.js

@@ -45,6 +45,8 @@ export const PHIS_CORE_CAPABILITIES = {
     settings: "@phis/server/settings:v1",
     /** Whether the acting user holds one of this Add-on's own declared roles. */
     roles: "@phis/server/roles:v1",
+    payments: "@phis/server/payments:v1",
+    paymentNotifications: "@phis/server/payment-notifications:v1",
 };
 /**
  * What Core tells an Add-on about after the fact.
@@ -66,6 +68,7 @@ export const PHIS_ADDON_EVENTS = {
     threadStatusChanged: "thread.status.changed",
     /** The link itself is gone; what follows from that is the Add-on's own business. */
     threadLinkRemoved: "thread.link.removed",
+    paymentChanged: "payment.changed",
 };
 /**
  * The Core-owned service kinds an Add-on may implement.
@@ -76,6 +79,7 @@ export const PHIS_ADDON_EVENTS = {
  */
 export const PHIS_SERVICE_KINDS = {
     mediaStorage: "@phis/server/service/media-storage",
+    payments: "@phis/server/service/payments",
     directory: "@phis/server/service/directory",
     /**
      * Turning text in one language into text in another.
@@ -86,6 +90,15 @@ export const PHIS_SERVICE_KINDS = {
      * operator selects which one an installation uses.
      */
     translation: "@phis/server/service/translation",
+    /**
+     * Handing a Support ticket's work to a system outside the Site -- an issue tracker, a ticket desk.
+     *
+     * A kind because Core owns the question: which ticket, which task, what may leave and what comes back.
+     * What the implementation talks to is its own business, and several may be installed at once; a
+     * Supporter chooses one per forward. The interface is `PhisSupportForwardingAdapterV1` in
+     * `@phis/contracts/support`.
+     */
+    supportForwarding: "@phis/server/service/support-forwarding",
 };
 /**
  * The digest of the interface each service kind currently has.
@@ -107,11 +120,15 @@ export const PHIS_SERVICE_KINDS = {
  */
 export const PHIS_SERVICE_INTERFACE_VERSIONS = {
     [PHIS_SERVICE_KINDS.mediaStorage]: 1,
+    [PHIS_SERVICE_KINDS.payments]: 1,
     [PHIS_SERVICE_KINDS.directory]: 1,
     [PHIS_SERVICE_KINDS.translation]: 1,
+    [PHIS_SERVICE_KINDS.supportForwarding]: 1,
 };
 export const PHIS_SERVICE_INTERFACE_DIGESTS = {
+    [PHIS_SERVICE_KINDS.payments]: "6b106818d5edbfeddd484e9f571509695a1a8dbb5b82435338a094216410fcf7",
     [PHIS_SERVICE_KINDS.mediaStorage]: "45a871522511f7d77841ca8dd0113b423b3cfd4cb921f143cd1d3d116cab6952",
     [PHIS_SERVICE_KINDS.directory]: "2cac7397c7beb1b8e71fc67f5cae3be89182dddf096895570a15deafa1adbfc9",
     [PHIS_SERVICE_KINDS.translation]: "9bae2e7b92ded5cdde9321939a3bb8cd589f6e1ef8bca7bc5f65608313b3207d",
+    [PHIS_SERVICE_KINDS.supportForwarding]: "e9d01711a5ebdfa37ea4c6828952c87935b6e755b98ab8e69cc397933dfbed6f",
 };

package/dist/payments.d.ts

@@ -0,0 +1,274 @@
+/**
+ * The approved v1 Payment agreement. Core owns execution; consumers own prices and commerce.
+ *
+ * Execution belongs to Core; its implemented capability, service and event identities live in core.ts.
+ * These declarations contain no SDK, credentials, persistence or exchange-rate conversion. See phis-server's
+ * PAYMENTS.md and PAYMENTS_STRIPE.md for authority, durability and Provider mapping requirements.
+ */
+export type PhisPaymentId = string;
+export type PhisPaymentOperationId = string;
+export type PhisPaymentRefundId = string;
+export type PhisPaymentMoney = {
+    /** Uppercase ISO currency code; one agreed currency for the whole payment. */
+    currency: string;
+    /** Canonical non-negative integer string of minor units, never floating-point money. */
+    minor: string;
+};
+export type PhisPaymentCaptureMode = "automatic" | "manual";
+export type PhisPaymentCheckoutKind = "redirect" | "provider-ui";
+export type PhisPaymentFeatures = {
+    captureModes: readonly PhisPaymentCaptureMode[];
+    checkoutKinds: readonly PhisPaymentCheckoutKind[];
+    canPartialCapture: boolean;
+    canCancel: boolean;
+    canRefund: boolean;
+    canPartialRefund: boolean;
+};
+export type PhisPaymentMethod = {
+    profileKey: string;
+    methodKey: string | null;
+    title: string;
+    features: PhisPaymentFeatures;
+};
+export type PhisPaymentCheckoutPlan = {
+    kind: "redirect";
+    url: string;
+    expiresAt: string | null;
+} | {
+    kind: "provider-ui";
+    moduleId: string;
+    adapterKey: string;
+    parameters: Readonly<Record<string, string>>;
+    expiresAt: string | null;
+};
+export type PhisPaymentStatus = "created" | "awaiting_customer" | "processing" | "authorized" | "captured" | "canceled" | "expired" | "failed";
+export type PhisPayment = {
+    id: PhisPaymentId;
+    reference: string;
+    profileKey: string;
+    mode: "test" | "live";
+    amount: PhisPaymentMoney;
+    captureMode: PhisPaymentCaptureMode;
+    status: PhisPaymentStatus;
+    authorizedMinor: string;
+    capturedMinor: string;
+    refundedMinor: string;
+    authorizationExpiresAt: string | null;
+    checkout: PhisPaymentCheckoutPlan | null;
+    reconciliationRequired: boolean;
+    version: number;
+    lastObservedAt: string | null;
+};
+export type PhisPaymentErrorCode = "invalid_input" | "not_found" | "forbidden" | "profile_unavailable" | "method_unavailable" | "unsupported_operation" | "invalid_state" | "active_attempt_exists" | "idempotency_conflict" | "payment_declined" | "provider_rejected" | "provider_unavailable" | "reconciliation_required";
+export type PhisPaymentOperation = {
+    id: PhisPaymentOperationId;
+    paymentId: PhisPaymentId;
+    action: "create" | "complete" | "capture" | "cancel" | "refund";
+    state: "reserved" | "pending" | "succeeded" | "failed" | "indeterminate";
+    errorCode: PhisPaymentErrorCode | null;
+};
+export type PhisPaymentRefund = {
+    id: PhisPaymentRefundId;
+    paymentId: PhisPaymentId;
+    amount: PhisPaymentMoney;
+    status: "pending" | "succeeded" | "failed" | "canceled";
+};
+export type PhisPaymentCommandResult = {
+    operation: PhisPaymentOperation;
+    payment: PhisPayment;
+    refund: PhisPaymentRefund | null;
+};
+export type PhisPaymentCreateInput = {
+    profileKey: string;
+    reference: string;
+    idempotencyKey: string;
+    amount: PhisPaymentMoney;
+    description: string;
+    captureMode: PhisPaymentCaptureMode;
+    methodKey: string | null;
+    checkoutKind: PhisPaymentCheckoutKind;
+    returnPath: string;
+};
+export type PhisPaymentCommandInput = {
+    paymentId: PhisPaymentId;
+    idempotencyKey: string;
+};
+export interface PhisPaymentsCapabilityV1 {
+    listMethods(input: {
+        profileKey: string;
+        amount: PhisPaymentMoney;
+        captureMode: PhisPaymentCaptureMode;
+        checkoutKind: PhisPaymentCheckoutKind;
+    }): Promise<readonly PhisPaymentMethod[]>;
+    /** Core binds Site/consumer/profile; the consumer checks access to its business resource. */
+    create(input: PhisPaymentCreateInput): Promise<PhisPaymentCommandResult>;
+    get(paymentId: PhisPaymentId): Promise<PhisPayment | null>;
+    getOperation(operationId: PhisPaymentOperationId): Promise<PhisPaymentOperation | null>;
+    getRefund(refundId: PhisPaymentRefundId): Promise<PhisPaymentRefund | null>;
+    /** Customer continuation; never captures a manually authorized payment. */
+    complete(input: PhisPaymentCommandInput): Promise<PhisPaymentCommandResult>;
+    /** Explicit bounded reconciliation that may update state and enqueue a consumer event. */
+    refresh(paymentId: PhisPaymentId): Promise<PhisPayment | null>;
+    /** One final merchant-authorized capture; minor units inherit the stored currency. */
+    capture(input: PhisPaymentCommandInput & {
+        minor: string;
+    }): Promise<PhisPaymentCommandResult>;
+    cancel(input: PhisPaymentCommandInput): Promise<PhisPaymentCommandResult>;
+    /** Merchant-authorized refund; pending/unknown amounts reserve the captured balance. */
+    refund(input: PhisPaymentCommandInput & {
+        minor: string;
+        reason: string;
+    }): Promise<PhisPaymentCommandResult>;
+}
+export type PhisPaymentProviderConfigV1 = {
+    profileKey: string;
+    mode: "test" | "live";
+    merchantIdentity: string | null;
+};
+export type PhisPaymentProviderContextV1 = {
+    providerKey: string;
+    readCredentials(): Promise<Readonly<Record<string, string>> | null>;
+};
+export type PhisPaymentProviderBinding = {
+    reference: string;
+    data: Readonly<Record<string, string>>;
+};
+export type PhisPaymentProviderProbe = {
+    merchantIdentity: string;
+    mode: "test" | "live";
+    methods: readonly Omit<PhisPaymentMethod, "profileKey">[];
+};
+export type PhisPaymentProviderObservation = {
+    binding: PhisPaymentProviderBinding;
+    merchantIdentity: string;
+    mode: "test" | "live";
+    status: PhisPaymentStatus;
+    amount: PhisPaymentMoney;
+    authorizedMinor: string;
+    capturedMinor: string;
+    authorizationExpiresAt: string | null;
+    checkout: PhisPaymentCheckoutPlan | null;
+    /** Complete refund observations, including remote refunds created outside Core. */
+    refunds: readonly {
+        operationId: PhisPaymentOperationId | null;
+        binding: PhisPaymentProviderBinding;
+        minor: string;
+        status: PhisPaymentRefund["status"];
+    }[];
+};
+export type PhisPaymentProviderCommand = {
+    operationId: PhisPaymentOperationId;
+    paymentId: PhisPaymentId;
+    providerIdempotencyKey: string;
+    signal: AbortSignal;
+} & ({
+    action: "create";
+    amount: PhisPaymentMoney;
+    description: string;
+    captureMode: PhisPaymentCaptureMode;
+    methodKey: string | null;
+    checkoutKind: PhisPaymentCheckoutKind;
+    returnUrl: string;
+    notificationUrl: string;
+} | {
+    action: "complete" | "cancel";
+    binding: PhisPaymentProviderBinding;
+} | {
+    action: "capture";
+    binding: PhisPaymentProviderBinding;
+    minor: string;
+} | {
+    action: "refund";
+    binding: PhisPaymentProviderBinding;
+    minor: string;
+    reason: string;
+});
+export type PhisPaymentProviderExecution = {
+    outcome: "applied" | "pending";
+    observation: PhisPaymentProviderObservation;
+} | {
+    outcome: "rejected";
+    code: PhisPaymentErrorCode;
+} | {
+    outcome: "unknown";
+};
+export type PhisPaymentProviderNotification = {
+    outcome: "verified";
+    deliveryId: string;
+    reference: string;
+} | {
+    outcome: "lookup-required";
+    reference: string;
+} | {
+    outcome: "irrelevant";
+} | {
+    outcome: "rejected";
+} | {
+    outcome: "unavailable";
+};
+export interface PhisPaymentProviderV1 {
+    probe(input: {
+        amount: PhisPaymentMoney;
+        captureMode: PhisPaymentCaptureMode;
+        checkoutKind: PhisPaymentCheckoutKind;
+        signal: AbortSignal;
+    }): Promise<PhisPaymentProviderProbe>;
+    execute(input: PhisPaymentProviderCommand): Promise<PhisPaymentProviderExecution>;
+    observe(input: {
+        binding: PhisPaymentProviderBinding;
+        signal: AbortSignal;
+    }): Promise<PhisPaymentProviderObservation>;
+    /** Recover the same command; never replace its key, merchant, mode or Provider. */
+    recover(input: {
+        command: PhisPaymentProviderCommand;
+        binding: PhisPaymentProviderBinding | null;
+    }): Promise<PhisPaymentProviderExecution>;
+    verifyNotification(input: {
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        body: Uint8Array;
+        signal: AbortSignal;
+    }): Promise<PhisPaymentProviderNotification>;
+}
+export interface PhisPaymentNotificationsCapabilityV1 {
+    receive(input: {
+        profileKey: string;
+    }): Promise<{
+        outcome: "processed" | "duplicate" | "ignored";
+    }>;
+}
+export type PhisPaymentGrantedOperation = "read" | "create" | "complete" | "refresh" | "capture" | "cancel" | "refund";
+export type PhisPaymentMerchantActionPolicy = {
+    roles: readonly string[];
+    jobs: readonly string[];
+    events: readonly string[];
+};
+export type PhisPaymentProfileGrant = {
+    consumerAddonId: string;
+    operations: readonly PhisPaymentGrantedOperation[];
+    merchantActions: {
+        capture: PhisPaymentMerchantActionPolicy;
+        cancel: PhisPaymentMerchantActionPolicy;
+        refund: PhisPaymentMerchantActionPolicy;
+    };
+};
+/** Operator-controlled references and grants; contains no credential values. */
+export type PhisPaymentProfileDraft = {
+    key: string;
+    providerKey: string;
+    mode: "test" | "live";
+    credentialReferences: Readonly<Record<string, string>>;
+    grants: readonly PhisPaymentProfileGrant[];
+};
+/** A payment event reaches only the consuming Add-on stored on that payment. */
+export type PhisPaymentChangedEventFacts = {
+    event: "payment.changed";
+    subject: {
+        kind: "payment";
+        paymentId: PhisPaymentId;
+        reference: string;
+        version: number;
+        operationId: PhisPaymentOperationId | null;
+        refundId: PhisPaymentRefundId | null;
+    };
+};

package/dist/payments.js

@@ -0,0 +1,8 @@
+/**
+ * The approved v1 Payment agreement. Core owns execution; consumers own prices and commerce.
+ *
+ * Execution belongs to Core; its implemented capability, service and event identities live in core.ts.
+ * These declarations contain no SDK, credentials, persistence or exchange-rate conversion. See phis-server's
+ * PAYMENTS.md and PAYMENTS_STRIPE.md for authority, durability and Provider mapping requirements.
+ */
+export {};

package/dist/references.d.ts

@@ -98,6 +98,15 @@ export type PhiLinkTarget = {
      * goes. Whether the reader may follow it is still the target Area's own answer.
      */
     area?: PhiCmsAreaKey;
+    /**
+     * The values of the Page's route parameters, where its route has any (`/news/:slug`).
+     *
+     * A reference names the route and not one address of it, so a link to one entry of a family of
+     * Pages states which: `{ slug: "launch" }`. The resolver answers the route's pattern, and the link
+     * fills it from here and from what its caller adds -- a list that links each of its entries states
+     * the route once and the value per entry. A parameter nobody fills leaves no link at all.
+     */
+    params?: Readonly<Record<string, string>>;
     fragment?: string | null;
     newTab?: boolean;
 } | {
@@ -121,10 +130,10 @@ 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.
+ * A route pattern with its parameters filled, or `null` while one is still open.
  *
- * 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.
+ * 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 declare function fillPhiRouteParams(pattern: string, params: Readonly<Record<string, string>> | null | undefined): string | null;
 export declare function readPhiLinkTarget(value: unknown): PhiLinkTarget | null;

package/dist/references.js

@@ -174,6 +174,37 @@ export function isPhiStorableExternalHref(value) {
  * 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;
@@ -192,10 +223,12 @@ export function readPhiLinkTarget(value) {
          * 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,
         };

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/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.6.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": [