@phreshos/core 0.1.2 → 0.1.4

package/dist/askable.d.ts

@@ -12,12 +12,11 @@ export interface Askable<Events extends object = {}, Fallback = unknown> extends
     /**
      * Sends one question payload to this target and waits for its answer.
      *
-     * The SDK uses a ten-second deadline by default. It sends the question only
-     * after the current Server incarnation becomes ready. The operation rejects
-     * immediately when that Server is absent, and also rejects if the incarnation
-     * stops before readiness or before answering. One SDK deadline covers both
-     * readiness and the answer. The boundary cannot infer whether an answerer
-     * exists, so a ready unanswered question waits for that deadline.
+     * The SDK uses a ten-second deadline by default. Any target-specific
+     * readiness wait shares that same deadline with the answer. The operation
+     * rejects when the target is known to be unavailable, or stops before
+     * answering. A boundary cannot infer whether an answerer exists, so a
+     * delivered but unanswered question waits for the deadline.
      */
     ask<Answer = unknown>(event: string): Promise<Answer>;
     ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>;

package/dist/channel.d.ts

@@ -1,5 +1,6 @@
 import type { Endpoint } from "./endpoint.js";
 import type { Publishable } from "./publishable.js";
+import type { ServiceDefinition } from "./service.js";
 import type { Captures, Subscribable } from "./subscribable.js";
 /** One application value arriving through the current Endpoint's Channel. */
 export type ChannelMessage<Payload = unknown, From = Endpoint> = Readonly<{
@@ -16,6 +17,10 @@ type ChannelFallback<Events extends object, From> = keyof Events extends never ?
 /** Every application event observable through a Channel. */
 export type ChannelCapture<Events extends object = {}, From = Endpoint> = Captures<ChannelEvents<Events, From>, ChannelFallback<Events, From>>;
 /** Addressed input and destinationless output for the executing Endpoint. */
-export interface Channel<Events extends object = {}, From = Endpoint> extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>>, Publishable {
+export interface Channel<Events extends object = {}, From = Endpoint, Definition extends ServiceDefinition = ServiceDefinition> extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>>, Publishable {
+    /** Exposes this executing Channel under one public service name. */
+    enableService(definition: Definition): Promise<void>;
+    /** Stops exposing this executing Channel as a service. */
+    disableService(): Promise<void>;
 }
 export {};

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { Endpoint, type EndpointTraffic } from "./endpoint.js";
 import type { LaunchClient } from "./launch.js";
 import type { Server } from "./server.js";
 import type { Window } from "./window.js";
+import type { ClientServiceHandler } from "./service.js";
 /** Directed communication originating from one Client. */
 export interface ClientTraffic<Events extends object = {}, To = Endpoint, AskTo = Server> extends EndpointTraffic<Events, To, AskTo> {
 }
@@ -16,4 +17,6 @@ export interface Client<Events extends object = {}> {
     readonly window: Window;
     /** Starts a fresh Client and Window using optional Process-local overrides. */
     start(overrides?: LaunchClient): Promise<void>;
+    /** Returns this Client's current complete service handle, or `null`. */
+    service<ServiceEvents extends object = {}>(): Promise<ClientServiceHandler<ServiceEvents> | null>;
 }

package/dist/config.d.ts

@@ -52,11 +52,6 @@ type Description = Readonly<{
     version?: string;
     /** Short human-readable explanation of what the Program does. */
     description?: string;
-    /**
-     * Markdown file describing only the Program-owned API contract.
-     * System access, Endpoint, and event mechanics belong to system documentation.
-     */
-    apiDocs?: string;
     /** PNG source between 128 and 2,048 pixels per side and no larger than 5 MiB. */
     icon?: string;
     /** Command run before production start, installation, and packaging. */

package/dist/endpoint.d.ts

@@ -1,6 +1,7 @@
 import type { Process } from "./process.js";
 import type { Publishable } from "./publishable.js";
 import type { Server } from "./server.js";
+import type { ServiceHandler } from "./service.js";
 import type { Captures, Cleanup, Subscribable } from "./subscribable.js";
 /** One application value observed in traffic originating from an Endpoint. */
 export type TrafficMessage<Payload = unknown, To = Endpoint> = Readonly<{
@@ -67,5 +68,7 @@ export interface Endpoint<Events extends object = {}> extends Publishable, Subsc
      * fails. Stopping never exits the Process implicitly.
      */
     stop(): Promise<void>;
+    /** Returns this Endpoint's current complete service handle, or `null`. */
+    service(): Promise<ServiceHandler | null>;
 }
 export {};

package/dist/main.d.ts

@@ -2,6 +2,7 @@ export { type Message, type Cleanup, type Capture, type Captures, type EventMess
 export { type Publishable } from "./publishable.js";
 export { type Timeoutable } from "./timeout.js";
 export { type Askable, type TimedAskable } from "./askable.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey, type ClientServiceChannel, type ServerServiceChannel, type ServerServiceDefinition, type ServiceChannel, type ServiceDefinition, type ServiceKey, type ServiceLifecycleEvents } from "./service.js";
 export { isPermissionName, permissionNames, type PermissionDecision, type PermissionDecisions, type PermissionName, type Permissions, type ProgramPermissions, type TimedPermissions } from "./permissions.js";
 export { type Outcome } from "./outcome.js";
 export { type ServedFile } from "./served-file.js";

package/dist/main.js

@@ -2,6 +2,7 @@ export {} from "./subscribable.js";
 export {} from "./publishable.js";
 export {} from "./timeout.js";
 export {} from "./askable.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey } from "./service.js";
 export { isPermissionName, permissionNames } from "./permissions.js";
 export {} from "./outcome.js";
 export {} from "./served-file.js";

package/dist/program.d.ts

@@ -83,11 +83,6 @@ export interface Program<Events extends object = {}> extends Subscribable<Progra
     getProcess(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this Program. */
     createProcess(launch?: Launch): Promise<Process>;
-    /**
-     * Returns the Program-authored API entry point, or `null`.
-     * The document describes the Program's contract, not system mechanics.
-     */
-    apiDocs(): Promise<string | null>;
     /**
      * Returns one standard PNG representation of this Program's icon.
      * Programs without an authored icon receive the system default.

package/dist/server.d.ts

@@ -2,6 +2,7 @@ import type { Askable } from "./askable.js";
 import { Endpoint, type EndpointTraffic } from "./endpoint.js";
 import type { Outcome } from "./outcome.js";
 import type { Cleanup } from "./subscribable.js";
+import type { ServerServiceHandler } from "./service.js";
 /** One answer sent by this Server to the Endpoint that asked. */
 export type AnswerMessage<Result = unknown, To = Endpoint> = Readonly<{
     /** Destination Endpoint, or `null` when its identity is outside this boundary. */
@@ -39,4 +40,6 @@ export interface Server<Events extends object = {}> extends Askable {
      * The SDK uses its ten-second deadline unless one is supplied.
      */
     waitReady(timeout?: number): Promise<void>;
+    /** Returns this Server's current complete service handle, or `null`. */
+    service<ServiceEvents extends object = {}>(): Promise<ServerServiceHandler<ServiceEvents> | null>;
 }

package/dist/service.d.ts

@@ -0,0 +1,73 @@
+import type { Askable } from "./askable.js";
+import type { Subscribable } from "./subscribable.js";
+/** Stable public coordinates of one explicitly named Endpoint service. */
+export type ServiceKey = Readonly<{
+    /** Stable identity of the Program that owns the providing Endpoint. */
+    program: string;
+    /** Endpoint kind deliberately exposed by the service author. */
+    endpoint: "server" | "client";
+    /** Program-authored service identity. */
+    name: string;
+}>;
+/** Runtime declaration of one service exposed by an Endpoint Channel. */
+export type ServiceDefinition = Readonly<{
+    /** Program-authored service identity. */
+    name: string;
+}>;
+/** Runtime declaration of one Server service and its optional API document. */
+export type ServerServiceDefinition = ServiceDefinition & Readonly<{
+    /** Complete API documentation owned by this service. */
+    docs?: string;
+}>;
+/** Lifecycle transitions of one exact service identity. */
+export type ServiceLifecycleEvents = {
+    /** A live Endpoint began providing this service. */
+    enable: undefined;
+    /** The providing Endpoint stopped exposing this service. */
+    disable: undefined;
+};
+/** Application events emitted by one service. */
+export interface ServiceChannel<Events extends object = {}> extends Subscribable<Events, keyof Events extends never ? unknown : never> {
+}
+/** Communication surface of a service provided by a Server Endpoint. */
+export interface ServerServiceChannel<Events extends object = {}> extends ServiceChannel<Events>, Askable {
+}
+/** Communication surface of a service provided by a Client Endpoint. */
+export interface ClientServiceChannel<Events extends object = {}> extends ServiceChannel<Events> {
+}
+/** Stable lifecycle handle for one exact public service identity. */
+export declare class ServiceHandler<Channel extends object = ServiceChannel> {
+    protected constructor();
+}
+export interface ServiceHandler<Channel extends object = ServiceChannel> extends Subscribable<ServiceLifecycleEvents, never> {
+    /** Program namespace of this service. */
+    readonly program: string;
+    /** Endpoint kind represented by this service. */
+    readonly endpoint: "server" | "client";
+    /** Program-authored service identity. */
+    readonly name: string;
+    /** Application communication, separate from service lifecycle. */
+    readonly channel: Channel;
+    /** Explicitly reads whether no live Endpoint currently provides the service. */
+    disabled(): Promise<boolean>;
+}
+/** Stable handle for one Server-provided service. */
+export declare class ServerServiceHandler<Events extends object = {}> extends ServiceHandler<ServerServiceChannel<Events>> {
+    protected constructor();
+}
+export interface ServerServiceHandler<Events extends object = {}> {
+    readonly endpoint: "server";
+    readonly channel: ServerServiceChannel<Events>;
+    /** Explicitly reads this live Server service's documentation, or `null`. */
+    docs(): Promise<string | null>;
+}
+/** Stable handle for one Client-provided service. */
+export declare class ClientServiceHandler<Events extends object = {}> extends ServiceHandler<ClientServiceChannel<Events>> {
+    protected constructor();
+}
+export interface ClientServiceHandler<Events extends object = {}> {
+    readonly endpoint: "client";
+    readonly channel: ClientServiceChannel<Events>;
+}
+/** Returns whether a boundary value is a complete service key. */
+export declare function isServiceKey(value: unknown): value is ServiceKey;

package/dist/service.js

@@ -0,0 +1,27 @@
+/** Stable lifecycle handle for one exact public service identity. */
+export class ServiceHandler {
+    constructor() { }
+}
+/** Stable handle for one Server-provided service. */
+export class ServerServiceHandler extends ServiceHandler {
+    constructor() {
+        super();
+    }
+}
+/** Stable handle for one Client-provided service. */
+export class ClientServiceHandler extends ServiceHandler {
+    constructor() {
+        super();
+    }
+}
+/** Returns whether a boundary value is a complete service key. */
+export function isServiceKey(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.program === "string"
+        && candidate.program.length > 0
+        && (candidate.endpoint === "server" || candidate.endpoint === "client")
+        && typeof candidate.name === "string"
+        && candidate.name.length > 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Environment-neutral contracts and domain objects for PhreshOS Programs.",
   "type": "module",
   "sideEffects": false,