@phis/contracts 0.3.1 → 0.5.0

package/dist/controls.js

@@ -0,0 +1,133 @@
+/**
+ * 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),
+            };
+        })
+            .filter((item) => item != null);
+    }
+    return [];
+}

package/dist/core.d.ts

@@ -47,6 +47,28 @@ export declare const PHIS_CORE_CAPABILITIES: {
     readonly roles: "@phis/server/roles:v1";
 };
 export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof PHIS_CORE_CAPABILITIES];
+/**
+ * What Core tells an Add-on about after the fact.
+ *
+ * An integration that mirrors a conversation cannot wait to be asked: somebody writes a reply here and
+ * it has to appear over there, and no request the Add-on serves is involved. Polling would be the
+ * alternative, and polling for "did anybody write anything" is the Site-wide read every capability here
+ * is shaped to prevent.
+ *
+ * An event is delivered only to an Add-on linked to the thread it happened in, and a message this same
+ * Add-on imported is never announced back to it -- which is what stops a mirror from echoing.
+ *
+ * The list is short on purpose and grows when an Add-on needs an entry, the way the capability catalogue
+ * does. Every event a Site could emit, declared in advance, would be a contract to get wrong.
+ */
+export declare const PHIS_ADDON_EVENTS: {
+    readonly threadMessageCreated: "thread.message.created";
+    readonly threadMessageUpdated: "thread.message.updated";
+    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";
+};
+export type PhisAddonEventId = (typeof PHIS_ADDON_EVENTS)[keyof typeof PHIS_ADDON_EVENTS];
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -57,6 +79,15 @@ export type PhisCoreCapabilityId = (typeof PHIS_CORE_CAPABILITIES)[keyof typeof
 export declare const PHIS_SERVICE_KINDS: {
     readonly mediaStorage: "@phis/server/service/media-storage";
     readonly directory: "@phis/server/service/directory";
+    /**
+     * Turning text in one language into text in another.
+     *
+     * A kind rather than a capability for the same reason as the two above: Core owns the question and
+     * keeps asking it, and what an implementation talks to -- a vendor, a model on the machine, a
+     * catalogue it maintains itself -- is its own business. Several may be installed at once; the
+     * operator selects which one an installation uses.
+     */
+    readonly translation: "@phis/server/service/translation";
 };
 export type PhisServiceKind = (typeof PHIS_SERVICE_KINDS)[keyof typeof PHIS_SERVICE_KINDS];
 /**
@@ -69,6 +100,13 @@ export type PhisServiceKind = (typeof PHIS_SERVICE_KINDS)[keyof typeof PHIS_SERV
  *
  * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
  * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ *
+ * **Before the v1 release every version here stays at 1, whatever changes shape.** There is no released
+ * Add-on to protect and nothing in the field built against an older interface, so raising a version buys
+ * no compatibility and costs the installation: the recorded manifest of every installed Add-on stops
+ * matching, `buildPhisCapabilitySnapshot` refuses the desired state, and every request that resolves a
+ * viewer answers 500 until each Add-on has been rebundled and upgraded. An interface that changes before
+ * v1 is simply the interface, and both sides are rebuilt from one tree.
  */
 export declare const PHIS_SERVICE_INTERFACE_VERSIONS: Readonly<Record<PhisServiceKind, number>>;
 export declare const PHIS_SERVICE_INTERFACE_DIGESTS: Readonly<Record<PhisServiceKind, string>>;

package/dist/core.js

@@ -46,6 +46,27 @@ export const PHIS_CORE_CAPABILITIES = {
     /** Whether the acting user holds one of this Add-on's own declared roles. */
     roles: "@phis/server/roles:v1",
 };
+/**
+ * What Core tells an Add-on about after the fact.
+ *
+ * An integration that mirrors a conversation cannot wait to be asked: somebody writes a reply here and
+ * it has to appear over there, and no request the Add-on serves is involved. Polling would be the
+ * alternative, and polling for "did anybody write anything" is the Site-wide read every capability here
+ * is shaped to prevent.
+ *
+ * An event is delivered only to an Add-on linked to the thread it happened in, and a message this same
+ * Add-on imported is never announced back to it -- which is what stops a mirror from echoing.
+ *
+ * The list is short on purpose and grows when an Add-on needs an entry, the way the capability catalogue
+ * does. Every event a Site could emit, declared in advance, would be a contract to get wrong.
+ */
+export const PHIS_ADDON_EVENTS = {
+    threadMessageCreated: "thread.message.created",
+    threadMessageUpdated: "thread.message.updated",
+    threadStatusChanged: "thread.status.changed",
+    /** The link itself is gone; what follows from that is the Add-on's own business. */
+    threadLinkRemoved: "thread.link.removed",
+};
 /**
  * The Core-owned service kinds an Add-on may implement.
  *
@@ -56,6 +77,15 @@ export const PHIS_CORE_CAPABILITIES = {
 export const PHIS_SERVICE_KINDS = {
     mediaStorage: "@phis/server/service/media-storage",
     directory: "@phis/server/service/directory",
+    /**
+     * Turning text in one language into text in another.
+     *
+     * A kind rather than a capability for the same reason as the two above: Core owns the question and
+     * keeps asking it, and what an implementation talks to -- a vendor, a model on the machine, a
+     * catalogue it maintains itself -- is its own business. Several may be installed at once; the
+     * operator selects which one an installation uses.
+     */
+    translation: "@phis/server/service/translation",
 };
 /**
  * The digest of the interface each service kind currently has.
@@ -67,12 +97,21 @@ export const PHIS_SERVICE_KINDS = {
  *
  * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
  * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ *
+ * **Before the v1 release every version here stays at 1, whatever changes shape.** There is no released
+ * Add-on to protect and nothing in the field built against an older interface, so raising a version buys
+ * no compatibility and costs the installation: the recorded manifest of every installed Add-on stops
+ * matching, `buildPhisCapabilitySnapshot` refuses the desired state, and every request that resolves a
+ * viewer answers 500 until each Add-on has been rebundled and upgraded. An interface that changes before
+ * v1 is simply the interface, and both sides are rebuilt from one tree.
  */
 export const PHIS_SERVICE_INTERFACE_VERSIONS = {
     [PHIS_SERVICE_KINDS.mediaStorage]: 1,
     [PHIS_SERVICE_KINDS.directory]: 1,
+    [PHIS_SERVICE_KINDS.translation]: 1,
 };
 export const PHIS_SERVICE_INTERFACE_DIGESTS = {
     [PHIS_SERVICE_KINDS.mediaStorage]: "45a871522511f7d77841ca8dd0113b423b3cfd4cb921f143cd1d3d116cab6952",
     [PHIS_SERVICE_KINDS.directory]: "2cac7397c7beb1b8e71fc67f5cae3be89182dddf096895570a15deafa1adbfc9",
+    [PHIS_SERVICE_KINDS.translation]: "9bae2e7b92ded5cdde9321939a3bb8cd589f6e1ef8bca7bc5f65608313b3207d",
 };