spfn 0.3.0-beta.13 → 0.3.0-beta.15

package/dist/surface.d.ts

@@ -0,0 +1,228 @@
+/**
+ * What a surface manifest describes and a call sends, as the client sees it.
+ */
+type SurfaceEffect = 'read' | 'write' | 'destructive';
+interface SurfaceModuleDescriptor {
+    id: string;
+    source: string;
+    contractVersion: string;
+    summary: string;
+}
+interface SurfaceCommandDescriptor {
+    name: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    module?: string;
+    summary?: string;
+    effect?: SurfaceEffect;
+    scopes?: string[];
+    /**
+     * Set when the app announced module metadata that failed validation, so
+     * this command's effect is unknown rather than absent. Callers must treat
+     * it as needing confirmation.
+     */
+    metadataRejected?: boolean;
+    input: {
+        params?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+        body?: Record<string, unknown>;
+    };
+}
+interface SurfaceManifest {
+    manifestVersion: 1;
+    modules?: SurfaceModuleDescriptor[];
+    commands: SurfaceCommandDescriptor[];
+}
+interface SurfaceCallInput {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    body: unknown | undefined;
+}
+interface SurfaceResponse {
+    status: number;
+    body: unknown;
+}
+
+/**
+ * Manifest trust
+ *
+ * The manifest is the app's own description of itself, and the client turns
+ * it into requests carrying a credential. So it is read as untrusted input:
+ * every command is checked against the surface's namespace before it can
+ * become a request, and what cannot be used is dropped with a warning rather
+ * than costing the caller every other command on the surface.
+ *
+ * Warnings go to the caller's sink with a structured description beside the
+ * message, so a CLI can word them in its own terms; nothing here writes to a
+ * terminal.
+ */
+
+/** What the client dropped from a manifest, and why. */
+type SurfaceWarning = {
+    kind: 'command';
+    reason: string;
+} | {
+    kind: 'metadata';
+    command: string;
+    reason: string;
+} | {
+    kind: 'modules';
+    reason: string;
+} | {
+    kind: 'module';
+    reason: string;
+};
+type SurfaceWarningSink = (message: string, warning: SurfaceWarning) => void;
+
+/**
+ * HTTP client for an app's command surface
+ *
+ * Talks to the running (usually deployed) app: fetches
+ * `GET <namespace>/_manifest` for command discovery and invokes commands
+ * against their declared method and path. The server owns validation — the
+ * client sends what its caller gave it and relays the server's answer.
+ *
+ * `spfn ops` is this client on `/_ops`; any namespace a `defineSurface`
+ * serves is reached the same way. The client writes nothing to a terminal:
+ * what it drops from a manifest goes to `onWarning`, and what it refuses is
+ * thrown — an app URL that would carry the credential in the clear among it.
+ *
+ * @example
+ * ```ts
+ * import { createSurfaceClient } from 'spfn/surface';
+ *
+ * const client = createSurfaceClient({
+ *     appUrl: 'https://app.example',
+ *     namespace: '/_app',
+ *     token: async () => issueToken(),
+ * });
+ * const answer = await client.call('pageAdd', { params: {}, query: {}, body: { title: 'Hello' } });
+ * ```
+ */
+
+interface SurfaceClientOptions {
+    /** The app's URL, base path included. https, or http against loopback. */
+    appUrl: string;
+    /** The surface's namespace, e.g. `/_app`. Its manifest is `<namespace>/_manifest`. */
+    namespace: string;
+    /** The bearer credential, or a function resolving it before each request. */
+    token: string | (() => Promise<string>);
+    /** Told about every command or module the client drops. Default: silent. */
+    onWarning?: SurfaceWarningSink;
+}
+interface SurfaceClient {
+    /** Fetch the manifest, keeping only the commands this client can call. */
+    manifest(): Promise<SurfaceManifest>;
+    /** One command's usage text, from a manifest already fetched. */
+    describe(manifest: SurfaceManifest, name: string): string;
+    /** Fetch the manifest and invoke the named command. */
+    call(name: string, input: SurfaceCallInput): Promise<SurfaceResponse>;
+    /** Invoke a command taken from a manifest already fetched. */
+    invoke(command: SurfaceCommandDescriptor, input: SurfaceCallInput): Promise<SurfaceResponse>;
+}
+/** The manifest request answered something other than 200. */
+declare class SurfaceManifestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Append an absolute path to the app URL, keeping whatever base path the
+ * caller gave.
+ *
+ * Concatenation rather than `new URL(path, appUrl)`, because an absolute path
+ * resolved against a base replaces it: an app mounted at
+ * `https://example.com/api` would be called at `https://example.com/_ops/...`.
+ * Every request goes through here so the two halves of the ops CLI — the ops
+ * calls and the administrator sign-in — agree about where the app is.
+ */
+declare function joinUrl(appUrl: string, path: string): string;
+/**
+ * Create a client for one surface of one app. The app URL and namespace are
+ * checked here, so a client that exists can only send its credential where
+ * it is safe to.
+ */
+declare function createSurfaceClient(options: SurfaceClientOptions): SurfaceClient;
+
+/**
+ * Command paths: whether a manifest's path template is safe to request, and
+ * the request path a call builds from it.
+ */
+
+/**
+ * Substitute `:name` segments from params. A missing parameter fails here,
+ * before any request leaves the machine.
+ *
+ * The template is checked for namespace escape, and each value for climbing
+ * out of its own segment. The substituted result is not re-checked: by then
+ * every value is encoded, and reading an operator's own `%` or `/` back as an
+ * attempted escape would refuse data the app accepts.
+ */
+declare function buildCommandPath(command: SurfaceCommandDescriptor, params: Record<string, string>, query: Record<string, string>, namespace: string): string;
+
+/**
+ * Terminal-safe rendering of app-supplied text
+ *
+ * Its own module because both the manifest client and the usage renderer need
+ * it, and the client must not import the renderer to get it.
+ */
+/**
+ * Strip what a terminal would act on rather than show.
+ *
+ * Every string rendered here — a field's description, its pattern, a command's
+ * name — is the app's, and it is written straight to the operator's terminal.
+ * Escape sequences left in it can clear the screen or redraw the lines above,
+ * so what the operator reads is no longer what the CLI wrote. Control
+ * characters are replaced rather than dropped, so text that contained them
+ * still reads as suspicious instead of quietly shrinking.
+ */
+declare function plain(value: string): string;
+
+/**
+ * Render a surface command's input schemas as usage text.
+ *
+ * The manifest carries each command's TypeBox schemas as plain JSON Schema,
+ * so the terminal can tell an operator what a command takes without the app's
+ * source. This turns that JSON into the shape a `--help` reader expects:
+ * one line per field, with its type, whether it is required, and whatever
+ * constraints the schema states.
+ *
+ * The server remains the authority on what is valid — this only reports what
+ * the server said.
+ */
+
+/**
+ * The whole usage block for one command: its method and path, then a section
+ * per input kind. A command taking no input says so rather than printing
+ * nothing.
+ *
+ * `invoke` is the command line that calls it — `spfn ops call` for the ops
+ * CLI — and adds an example invocation line; a library caller has none.
+ */
+declare function renderCommandUsage(command: SurfaceCommandDescriptor, invoke?: string): string;
+
+/**
+ * The transport rule every surface request obeys: https, or http against the
+ * machine itself.
+ *
+ * Every request a surface client makes carries a credential — an ops token, a
+ * signed token, an administrator's password on `spfn ops token issue`. A stale
+ * app URL left over from a local run, or a typo, is enough to put it on the
+ * wire unencrypted, and nothing about the answer would say so. The client
+ * refuses such a URL when it is created; `spfn ops` asks the same question
+ * first so it can render the refusal its own way.
+ */
+/** Why an app URL may not carry a credential, or null when it may. */
+type TransportRefusal = 'cleartext-http' | 'not-http';
+/**
+ * Where `http` is not a mistake: a machine talking to itself, which has no
+ * certificate to present and no network for anyone to listen on.
+ *
+ * The scaffold's own API runs on `http://localhost:8790`, so local development
+ * has to keep working — but that is the whole of the exception.
+ */
+declare function isLoopback(hostname: string): boolean;
+declare function transportRefusalOf(url: URL): TransportRefusal | null;
+/** Throw unless `appUrl` is an absolute https URL, or http against loopback. */
+declare function assertTransportSafe(appUrl: string): void;
+
+export { type SurfaceCallInput, type SurfaceClient, type SurfaceClientOptions, type SurfaceCommandDescriptor, type SurfaceEffect, type SurfaceManifest, SurfaceManifestError, type SurfaceModuleDescriptor, type SurfaceResponse, type SurfaceWarning, type SurfaceWarningSink, type TransportRefusal, assertTransportSafe, buildCommandPath, createSurfaceClient, isLoopback, joinUrl, plain, renderCommandUsage, transportRefusalOf };