@printobserver/sdk 0.2.0 → 0.3.0

package/dist/client.d.ts

@@ -24,9 +24,11 @@ export interface ClientOptions {
     /** Who this client acts as. */
     actor: Actor;
     /**
-     * What authenticates to it. This server requires none of its API callers; a
-     * credential is for a deployment that has put something in front of it that
-     * does.
+     * What authenticates to it. The supervisor serves no versioned operation to a
+     * caller that does not present the credential it is configured with — its
+     * `api.credential`, or the one it generated into its state directory and
+     * wrote into the client configuration beside it — and a call it refuses for
+     * that throws `Refused` with status 401.
      */
     credential?: string;
 }

package/dist/contract.d.ts

@@ -8,15 +8,17 @@
  */
 import { GeneratedSurface } from "./surface.ts";
 /**
- * The version of the server contract these types were generated from, which
- * is the version the type crate declares in the tree they came from.
+ * The version of the server contract these types were generated from. A
+ * published package reports the release version it was built at; used from a
+ * checkout, this module reports that checkout's workspace version, and
+ * refuses to import when it cannot read one.
  */
-export declare const CONTRACT_VERSION = "0.2.0";
+export declare const CONTRACT_VERSION: string;
 /**
  * Every operation this client exposes a method for, which is every operation
  * the server declares and no other.
  */
-export declare const OPERATION_NAMES: readonly ["status", "context", "image", "history", "manifest_get", "manifest_set", "pause", "resume", "cancel", "start_print", "set_feedrate_factor", "set_flowrate_factor", "set_tool_target_c", "set_bed_target_c", "set_fan_percent", "acknowledge_failure"];
+export declare const OPERATION_NAMES: readonly ["prints", "status", "context", "image", "history", "manifest_get", "manifest_set", "pause", "resume", "cancel", "start_print", "set_feedrate_factor", "set_flowrate_factor", "set_tool_target_c", "set_bed_target_c", "set_fan_percent", "acknowledge_failure"];
 /** What an operator's acknowledgement of a failure event asks for next. */
 export type AcknowledgementDisposition = "continue" | "watch" | "stop";
 /** What one mutating request left behind it. */
@@ -175,9 +177,12 @@ export interface ErrorAnswer {
 /** A lowercase hyphenated version 7 UUID identifying one event. */
 export type EventId = string;
 /**
- * What every arm of `EventRecord` carries beside its own payload.
- *
- * One event, as the store holds it.
+ * The name one kind of event is written down under: lowercase `snake_case`,
+ * declared by the domain that owns the event.
+ */
+export type EventKind = string;
+/**
+ * One event, as the store holds it and the server serves it.
  *
  * `raw` holds the bytes exactly as received for an externally sourced event
  * and is absent for an internally raised one — it is what makes the history
@@ -186,11 +191,15 @@ export type EventId = string;
  * system
  * knows.
  */
-export interface EventRecordCommon {
+export interface EventRecord {
     /** This event's identifier, minted by the store. */
     id: EventId;
     /** The image it arrived with, when it arrived with one. */
     image?: ImageRef | null;
+    /** Which event this is. */
+    kind: EventKind;
+    /** What it carries, in the form its kind declares. */
+    payload: unknown;
     /** The print it belongs to, when it belongs to one. */
     print_id?: PrintId | null;
     /** The bytes exactly as received, for an externally sourced event. */
@@ -201,57 +210,10 @@ export interface EventRecordCommon {
     source: EventSource;
 }
 /**
- * One event, as the store holds it.
- *
- * `raw` holds the bytes exactly as received for an externally sourced event
- * and is absent for an internally raised one — it is what makes the history
- * auditable when a normalization turns out to be wrong. `print_id` is
- * optional, because an externally sourced event may name no print this
- * system
- * knows.
+ * Where an event came from, as the bare string the domain that raised it
+ * declares for itself.
  */
-export type EventRecord = (EventRecordCommon & {
-    kind: "obico_failure_alert";
-    payload: ObicoFailureAlertPayload;
-}) | (EventRecordCommon & {
-    kind: "obico_printer_notification";
-    payload: ObicoPrinterNotificationPayload;
-}) | (EventRecordCommon & {
-    kind: "malformed_external_event";
-    payload: MalformedExternalEventPayload;
-}) | (EventRecordCommon & {
-    kind: "action_requested";
-    payload: ActionRequestedPayload;
-}) | (EventRecordCommon & {
-    kind: "action_executed";
-    payload: ActionExecutedPayload;
-}) | (EventRecordCommon & {
-    kind: "action_rejected";
-    payload: ActionRejectedPayload;
-}) | (EventRecordCommon & {
-    kind: "intervention_expired";
-    payload: InterventionExpiredPayload;
-}) | (EventRecordCommon & {
-    kind: "supervision_session_opened";
-    payload: SupervisionSessionOpenedPayload;
-}) | (EventRecordCommon & {
-    kind: "supervision_session_closed";
-    payload: SupervisionSessionClosedPayload;
-}) | (EventRecordCommon & {
-    kind: "agent_assessment";
-    payload: AgentAssessmentPayload;
-}) | (EventRecordCommon & {
-    kind: "operator_acknowledgement";
-    payload: OperatorAcknowledgementPayload;
-}) | (EventRecordCommon & {
-    kind: "port_failure";
-    payload: PortFailurePayload;
-}) | (EventRecordCommon & {
-    kind: "startup_reconciliation";
-    payload: StartupReconciliationPayload;
-});
-/** Where an event came from. */
-export type EventSource = "obico" | "operator" | "agent" | "system";
+export type EventSource = string;
 /** What happened when an accepted action reached the printer. */
 export type ExecutionOutcome = "succeeded" | {
     failed: {
@@ -640,9 +602,9 @@ export type PrintId = string;
 /**
  * One print, and the record supervision keys from.
  *
- * Obico's own print id is carried beside this record's identifier rather
- * than
- * as it, because a print may be observed before Obico has one.
+ * The provider's own print id is carried beside this record's identifier
+ * rather than as it, because a print may be observed before the provider
+ * that reports it has one.
  */
 export interface PrintRecord {
     /** Why it ended, if it has. */
@@ -655,10 +617,13 @@ export interface PrintRecord {
     id: PrintId;
     /** Every manifest range this print narrowed to the envelope's. */
     narrowings: Array<ManifestNarrowing>;
-    /** Obico's own identifier for the print, when Obico has one. */
-    obico_print_id?: number | null;
     /** When the print was opened. */
     opened_at: Timestamp;
+    /**
+     * The provider's own identifier for the print, whichever provider
+     * reported it, when one has.
+     */
+    provider_print_id?: number | null;
     /** The state the print is in. */
     state: PrinterState;
 }
@@ -690,6 +655,24 @@ export interface PrinterSnapshot {
 export type PrinterState = "operational" | "paused" | "printing" | "cancelling" | "error" | "offline" | {
     unknown: string;
 };
+/**
+ * What the prints read answers: every print, and the one the printer is
+ * running.
+ *
+ * An open print's recorded `state` is the state it was opened in, which is
+ * `printing` whether or not the machine is paused now; what the machine is
+ * doing is the status read's answer.
+ */
+export interface PrintsAnswer {
+    /**
+     * The print the printer's current job belongs to, present exactly when the
+     * printer reports a job it is printing or has paused. Absent when the
+     * printer could not be read.
+     */
+    active?: PrintId | null;
+    /** Every print this server holds, ended or not, most recently opened first. */
+    prints: Array<PrintRecord>;
+}
 /** An inclusive pair of 64-bit floats. */
 export interface Range {
     /** The highest value the range admits, inclusive. */
@@ -815,6 +798,35 @@ export interface SupervisionSessionOpenedPayload {
 }
 /** An instant in UTC, as an RFC 3339 string with a zero offset. */
 export type Timestamp = string;
+/**
+ * Every kind the server declares a payload type for, keyed by the kind's
+ * name, and the type each payload has. A kind this client does not know
+ * flows through `EventRecord` untouched, and is in no table.
+ */
+export interface EventPayloads {
+    action_executed: ActionExecutedPayload;
+    action_rejected: ActionRejectedPayload;
+    action_requested: ActionRequestedPayload;
+    agent_assessment: AgentAssessmentPayload;
+    intervention_expired: InterventionExpiredPayload;
+    malformed_external_event: MalformedExternalEventPayload;
+    obico_failure_alert: ObicoFailureAlertPayload;
+    obico_printer_notification: ObicoPrinterNotificationPayload;
+    operator_acknowledgement: OperatorAcknowledgementPayload;
+    port_failure: PortFailurePayload;
+    startup_reconciliation: StartupReconciliationPayload;
+    supervision_session_closed: SupervisionSessionClosedPayload;
+    supervision_session_opened: SupervisionSessionOpenedPayload;
+}
+/** Every kind the server declares a payload type for, in name order. */
+export declare const EVENT_KINDS: readonly ["action_executed", "action_rejected", "action_requested", "agent_assessment", "intervention_expired", "malformed_external_event", "obico_failure_alert", "obico_printer_notification", "operator_acknowledgement", "port_failure", "startup_reconciliation", "supervision_session_closed", "supervision_session_opened"];
+/**
+ * The payload of one event as the type its kind declares, or `undefined` for
+ * an event of any other kind — one this client knows or one it does not. No
+ * validation beyond the kind's name: the payload is the document the server
+ * sent, handed on as the type the table says it is.
+ */
+export declare function payloadOf<K extends keyof EventPayloads>(event: EventRecord, kind: K): EventPayloads[K] | undefined;
 /**
  * One method per operation the server declares.
  *
@@ -823,6 +835,14 @@ export type Timestamp = string;
  * vocabulary are hand-written, and this class is written against them.
  */
 export declare class GeneratedClient extends GeneratedSurface {
+    /**
+     * Call `prints` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    prints(): Promise<PrintsAnswer>;
     /**
      * Call `status` on the configured supervisor.
      *

package/dist/contract.js

@@ -7,16 +7,13 @@
  *  generate-clients`, and commit what that writes.
  */
 import { GeneratedSurface, reasonGiven } from "./surface.js";
-/**
- * The version of the server contract these types were generated from, which
- * is the version the type crate declares in the tree they came from.
- */
-export const CONTRACT_VERSION = "0.2.0";
+export const CONTRACT_VERSION = "0.3.0";
 /**
  * Every operation this client exposes a method for, which is every operation
  * the server declares and no other.
  */
 export const OPERATION_NAMES = [
+    "prints",
     "status",
     "context",
     "image",
@@ -34,6 +31,34 @@ export const OPERATION_NAMES = [
     "set_fan_percent",
     "acknowledge_failure",
 ];
+/** Every kind the server declares a payload type for, in name order. */
+export const EVENT_KINDS = [
+    "action_executed",
+    "action_rejected",
+    "action_requested",
+    "agent_assessment",
+    "intervention_expired",
+    "malformed_external_event",
+    "obico_failure_alert",
+    "obico_printer_notification",
+    "operator_acknowledgement",
+    "port_failure",
+    "startup_reconciliation",
+    "supervision_session_closed",
+    "supervision_session_opened",
+];
+/**
+ * The payload of one event as the type its kind declares, or `undefined` for
+ * an event of any other kind — one this client knows or one it does not. No
+ * validation beyond the kind's name: the payload is the document the server
+ * sent, handed on as the type the table says it is.
+ */
+export function payloadOf(event, kind) {
+    if (event.kind !== kind) {
+        return undefined;
+    }
+    return event.payload;
+}
 /**
  * One method per operation the server declares.
  *
@@ -42,6 +67,21 @@ export const OPERATION_NAMES = [
  * vocabulary are hand-written, and this class is written against them.
  */
 export class GeneratedClient extends GeneratedSurface {
+    /**
+     * Call `prints` on the configured supervisor.
+     *
+     * Rejects with `Unreachable` when nothing answered, with `Unreadable` when
+     * the answer could not be read, and with `Refused` when the supervisor
+     * said no.
+     */
+    // llmlint: ignore[names_match_behavior] See suppressions.toml.
+    async prints() {
+        const target = `/v1/prints`;
+        const asked = [];
+        const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
+        return await this.call("GET", target, asked, sending);
+    }
     /**
      * Call `status` on the configured supervisor.
      *
@@ -53,6 +93,7 @@ export class GeneratedClient extends GeneratedSurface {
         const target = `/v1/prints/${printId}/status`;
         const asked = [];
         const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("GET", target, asked, sending);
     }
     /**
@@ -66,6 +107,7 @@ export class GeneratedClient extends GeneratedSurface {
         const target = `/v1/prints/${printId}/context`;
         const asked = [];
         const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("GET", target, asked, sending);
     }
     /**
@@ -79,6 +121,7 @@ export class GeneratedClient extends GeneratedSurface {
         const target = `/v1/images/${imageId}`;
         const asked = [];
         const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("GET", target, asked, sending);
     }
     /**
@@ -95,6 +138,7 @@ export class GeneratedClient extends GeneratedSurface {
             asked.push(["limit", String(limit)]);
         }
         const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("GET", target, asked, sending);
     }
     /**
@@ -108,6 +152,7 @@ export class GeneratedClient extends GeneratedSurface {
         const target = `/v1/prints/${printId}/manifest`;
         const asked = [];
         const sending = undefined;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("GET", target, asked, sending);
     }
     /**
@@ -126,6 +171,7 @@ export class GeneratedClient extends GeneratedSurface {
         const sending = {};
         sending.reason = reason;
         sending.manifest = manifest;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("PUT", target, asked, sending);
     }
     /**
@@ -144,6 +190,7 @@ export class GeneratedClient extends GeneratedSurface {
         const sending = {};
         sending.actor = this.actor;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -162,6 +209,7 @@ export class GeneratedClient extends GeneratedSurface {
         const sending = {};
         sending.actor = this.actor;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -180,6 +228,7 @@ export class GeneratedClient extends GeneratedSurface {
         const sending = {};
         sending.actor = this.actor;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -200,6 +249,7 @@ export class GeneratedClient extends GeneratedSurface {
         sending.file_name = fileName;
         sending.manifest = manifest;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -222,6 +272,7 @@ export class GeneratedClient extends GeneratedSurface {
         }
         sending.factor = factor;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -244,6 +295,7 @@ export class GeneratedClient extends GeneratedSurface {
         }
         sending.factor = factor;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -267,6 +319,7 @@ export class GeneratedClient extends GeneratedSurface {
         sending.reason = reason;
         sending.target_c = targetC;
         sending.tool = tool;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -289,6 +342,7 @@ export class GeneratedClient extends GeneratedSurface {
         }
         sending.reason = reason;
         sending.target_c = targetC;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -311,6 +365,7 @@ export class GeneratedClient extends GeneratedSurface {
         }
         sending.percent = percent;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
     /**
@@ -331,6 +386,7 @@ export class GeneratedClient extends GeneratedSurface {
         sending.disposition = disposition;
         sending.event_id = eventId;
         sending.reason = reason;
+        // llmlint: ignore[boundary_inputs_validated] See suppressions.toml.
         return await this.call("POST", target, asked, sending);
     }
 }

package/package.json

@@ -12,12 +12,12 @@
   "license": "MIT",
   "main": "dist/index.js",
   "name": "@printobserver/sdk",
-  "printobserverContractVersion": "0.2.0",
+  "printobserverContractVersion": "0.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/nickderobertis/printobserver"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.2.0"
+  "version": "0.3.0"
 }