@phis/contracts 0.4.0 → 0.6.0

package/dist/controls.d.ts

@@ -0,0 +1,91 @@
+/**
+ * What a choice control offers, and where it asks for its choices when they are not written out.
+ *
+ * Here because stored descriptors carry both: a Form field lists its options or names the provider
+ * that answers for them, and phis-server reads that field as it is stored.
+ */
+export type PhiRuntimeDataProviderKey = `${string}/${string}`;
+/**
+ * `<namespace>/<name>`: an identifier that says whose it is.
+ *
+ * Provider keys, item renderer keys and everything else a Module may contribute to a shared registry
+ * share this shape, so they share one check. A second spelling of it is the one that drifts.
+ */
+export declare function isPhiNamespacedRuntimeKey(value: unknown): value is `${string}/${string}`;
+export declare function isPhiRuntimeDataProviderKey(value: unknown): value is PhiRuntimeDataProviderKey;
+export type PhiControlOption<TValue extends string | number = string> = {
+    value: TValue;
+    label: string;
+    disabled?: boolean;
+    description?: string;
+    icon?: string;
+    preview?: PhiControlOptionPreview;
+    /**
+     * The heading this option is listed under, where the Control can group -- a Select shows consecutive
+     * options with the same group under one heading. A Control that cannot group lists the options as they
+     * 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.
+ *
+ * `fontFamily` is a complete `font-family` value -- a family, its fallback, a generic -- because the
+ * option is drawn in a popup outside the page's root, where a variable that names a font is not in
+ * scope. Whoever builds the option resolves the variable first.
+ */
+export type PhiControlOptionFontPreview = {
+    kind: "font";
+    fontFamily: string;
+};
+export type PhiControlOptionBackgroundPreview = {
+    kind: "background";
+    backgroundColor?: string;
+    backgroundImage?: string;
+    backgroundSize?: string;
+    backgroundPosition?: string;
+    backgroundRepeat?: string;
+};
+export type PhiControlOptionsProviderLoadMode = "client" | "server" | "hybrid";
+export type PhiControlOptionsProviderSearchConfig = {
+    enabled?: boolean;
+    minChars?: number;
+};
+/**
+ * A value this provider needs that another field holds.
+ *
+ * `source` and `valuePath` are the vocabulary conditions already use, so "the value of a sibling field"
+ * is said the same way everywhere. `form` reads the live form values; `config` reads the field or Widget
+ * configuration the control was built from, which is what an Inspector has instead of a form.
+ *
+ * `required` is the difference between narrowing a list and having no list: a provider whose answer is
+ * meaningless without the parent value is not asked at all until it has one, rather than answering with
+ * everything and looking as if the dependency were ignored.
+ */
+export type PhiControlOptionsProviderDependency = {
+    /** The name the provider reads this value under. */
+    param: string;
+    source: "form" | "config";
+    valuePath: string;
+    required?: boolean;
+};
+export type PhiControlOptionsProviderConfig = {
+    providerKey: PhiRuntimeDataProviderKey;
+    scopeKey?: string;
+    area?: string;
+    params?: Record<string, unknown>;
+    loadMode?: PhiControlOptionsProviderLoadMode;
+    search?: PhiControlOptionsProviderSearchConfig;
+    dependencies?: readonly PhiControlOptionsProviderDependency[];
+};
+export declare function parsePhiControlOptionsProviderConfig(value: unknown): PhiControlOptionsProviderConfig | null;
+export declare function readPhiControlOptions(value: unknown): PhiControlOption[];

package/dist/controls.js

@@ -0,0 +1,134 @@
+/**
+ * What a choice control offers, and where it asks for its choices when they are not written out.
+ *
+ * Here because stored descriptors carry both: a Form field lists its options or names the provider
+ * that answers for them, and phis-server reads that field as it is stored.
+ */
+/**
+ * `<namespace>/<name>`: an identifier that says whose it is.
+ *
+ * Provider keys, item renderer keys and everything else a Module may contribute to a shared registry
+ * share this shape, so they share one check. A second spelling of it is the one that drifts.
+ */
+export function isPhiNamespacedRuntimeKey(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const separatorIndex = value.lastIndexOf("/");
+    return separatorIndex > 0 && separatorIndex < value.length - 1;
+}
+export function isPhiRuntimeDataProviderKey(value) {
+    return isPhiNamespacedRuntimeKey(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function readRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function readLoadMode(value) {
+    return value === "client" || value === "server" || value === "hybrid" ? value : undefined;
+}
+function readSearchConfig(value) {
+    const record = readRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    const enabled = typeof record.enabled === "boolean" ? record.enabled : undefined;
+    const minChars = typeof record.minChars === "number" && Number.isFinite(record.minChars)
+        ? Math.max(0, Math.trunc(record.minChars))
+        : undefined;
+    if (enabled === undefined && minChars === undefined) {
+        return undefined;
+    }
+    return {
+        enabled,
+        minChars,
+    };
+}
+function readDependencies(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const dependencies = value.flatMap((entry) => {
+        const record = readRecord(entry);
+        const param = readString(record?.param);
+        const valuePath = readString(record?.valuePath);
+        const source = record?.source === "form" || record?.source === "config" ? record.source : undefined;
+        if (!param || !valuePath || !source) {
+            return [];
+        }
+        return [{
+                param,
+                source,
+                valuePath,
+                required: record?.required === true ? true : undefined,
+            }];
+    });
+    return dependencies.length > 0 ? dependencies : undefined;
+}
+function readOptionPreview(value) {
+    const record = readRecord(value);
+    if (record?.kind === "font") {
+        const fontFamily = readString(record.fontFamily);
+        return fontFamily ? { kind: "font", fontFamily } : undefined;
+    }
+    if (record?.kind !== "background")
+        return undefined;
+    return {
+        kind: "background",
+        backgroundColor: readString(record.backgroundColor),
+        backgroundImage: readString(record.backgroundImage),
+        backgroundSize: readString(record.backgroundSize),
+        backgroundPosition: readString(record.backgroundPosition),
+        backgroundRepeat: readString(record.backgroundRepeat),
+    };
+}
+export function parsePhiControlOptionsProviderConfig(value) {
+    const record = readRecord(value);
+    if (!record) {
+        return null;
+    }
+    const providerKey = readString(record.providerKey);
+    if (!isPhiRuntimeDataProviderKey(providerKey)) {
+        return null;
+    }
+    return {
+        providerKey,
+        scopeKey: readString(record.scopeKey),
+        area: readString(record.area),
+        params: readRecord(record.params),
+        loadMode: readLoadMode(record.loadMode),
+        search: readSearchConfig(record.search),
+        dependencies: readDependencies(record.dependencies),
+    };
+}
+export function readPhiControlOptions(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item)) {
+                return null;
+            }
+            const record = item;
+            const optionValue = readString(record.value);
+            if (!optionValue) {
+                return null;
+            }
+            return {
+                value: optionValue,
+                label: readString(record.label) ?? optionValue,
+                disabled: typeof record.disabled === "boolean" ? record.disabled : undefined,
+                description: readString(record.description),
+                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);
+    }
+    return [];
+}

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",
 };