apps 0.0.1-beta.42 → 0.0.1-beta.43

package/types/telemetry/src/browser-operations.d.ts

@@ -8,7 +8,7 @@ import { HttpClient, HttpClientError } from "effect/http";
 export declare const browserPageId: () => string | undefined;
 /** Safe event shared with the host's error reporter and product analytics. */
 export declare const BrowserOperationFailure: Schema.Struct<{
-    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
+    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserConnectionFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
     readonly trace_id: Schema.String;
     readonly span_id: Schema.String;
     readonly page_id: Schema.String;

package/types/utils/src/connection-failure.d.ts

@@ -0,0 +1,33 @@
+/** Requests the browser could not complete because no response reached it. */
+import { Cause } from "effect";
+import { HttpClientError } from "effect/http";
+import { UserFacingError } from "./user-facing-error.js";
+/**
+ * Fetch rejects with a `TypeError` when no response arrives: the device is offline, the page
+ * navigated away first, the connection was reset before a response, or the browser blocked the
+ * request. The server may still have completed the request and records its own outcome. Failures Executor constructs itself, such as a batch reply
+ * that ended without an answer, carry no such cause and stay unexpected.
+ */
+export declare const isConnectionFailure: (error: unknown) => error is HttpClientError.HttpClientError;
+/** Typed API clients may surface a lost connection as a failure or, after narrowing, a defect. */
+export declare const hasConnectionFailure: (cause: Cause.Cause<unknown>) => boolean;
+/** The browser could not reach Executor. Nothing on the server needs fixing. */
+export declare const ConnectionFailed: import("effect/Schema").Class<{} & UserFacingError & {
+    readonly _tag: "ConnectionFailed";
+}, Omit<import("effect/Schema").TaggedStruct<"ConnectionFailed", {
+    readonly message: typeof import("./api-error.js").MessageField;
+    readonly recovery: import("effect/Schema").decodeTo<import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+        readonly action: import("effect/Schema").String;
+        readonly instructions: import("effect/Schema").String;
+    }>>, import("effect/Schema").Struct<{
+        readonly action: import("effect/Schema").String;
+        readonly instructions: import("effect/Schema").String;
+    }>, never, never>;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": {
+        readonly _tag?: "ConnectionFailed";
+    };
+}, UserFacingError>;
+export type ConnectionFailed = typeof ConnectionFailed.Type;
+/** What to show for a failure no contract declares: a lost connection, or an unexpected error. */
+export declare const undeclaredError: (cause: Cause.Cause<unknown>) => UserFacingError;

package/types/utils/src/user-facing-error.d.ts

@@ -0,0 +1,81 @@
+import { Schema, type Cause } from "effect";
+import "effect/http-api";
+import { MessageField } from "./api-error.js";
+/** Curated explanation and recovery. Never include raw diagnostics, credentials, or form values. */
+export interface ErrorPresentation {
+    readonly title: string;
+    readonly description: string;
+    readonly recovery: {
+        readonly action: string;
+        readonly instructions: string;
+    };
+    /** Repeating the failed operation can help. Configuration changes are not retries. */
+    readonly retryable?: boolean;
+    /** False when the user's agent cannot act on the fix prompt, so hosts do not offer it. */
+    readonly agentFixable?: boolean;
+    /** One safe value the user needs for recovery, such as a URL to send to the service. */
+    readonly detail?: {
+        readonly label: string;
+        readonly value: string;
+    };
+    /**
+     * Present only when the Executor team must fix the problem. Safe evidence for a public
+     * report: fixed codes and statuses, never user data, URLs, or upstream text.
+     */
+    readonly report?: string;
+}
+type PresentationProperties = Required<Omit<ErrorPresentation, "detail" | "report">> & {
+    readonly detail: ErrorPresentation["detail"];
+    readonly report: ErrorPresentation["report"];
+    readonly code: string;
+    readonly fixPrompt: string;
+};
+/** A yieldable error that owns its safe user explanation and agent recovery task. */
+export interface UserFacingError extends Cause.YieldableError, PresentationProperties {
+    readonly _tag: string;
+}
+type Header<Tag extends string> = {
+    readonly tag: Tag;
+    readonly status: number;
+};
+type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Header<Tag> & {
+    readonly fields: Fields & {
+        readonly [Key in keyof PresentationProperties | "_tag" | "message"]?: never;
+    };
+    /**
+     * What traces and error reports record instead of the description, when the description quotes
+     * an app's own error or a service's stated error for its caller. Only fixed text and typed fields.
+     */
+    readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
+} & (ErrorPresentation | {
+    readonly presentation: (fields: Schema.Struct.Type<Fields>) => ErrorPresentation;
+});
+declare const RecoveryField: Schema.decodeTo<Schema.optionalKey<Schema.Struct<{
+    readonly action: Schema.String;
+    readonly instructions: Schema.String;
+}>>, Schema.Struct<{
+    readonly action: Schema.String;
+    readonly instructions: Schema.String;
+}>, never, never>;
+type DerivedFields = {
+    readonly message: typeof MessageField;
+    readonly recovery: typeof RecoveryField;
+};
+type ErrorFields<Tag extends string, Fields extends Schema.Struct.Fields> = Omit<Schema.TaggedStruct<Tag, Fields & DerivedFields>, "~type.make.in"> & {
+    readonly "~type.make.in": Schema.TaggedStruct<Tag, Fields>["~type.make.in"];
+};
+type ErrorClass<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Class<Schema.Struct.Type<Fields> & UserFacingError & {
+    readonly _tag: Tag;
+}, ErrorFields<Tag, Fields>, UserFacingError>;
+/** Define a schema-backed error with no payload. Its tag becomes its public error code. */
+declare function define<const Tag extends string>(definition: Header<Tag> & ErrorPresentation): ErrorClass<Tag, {}>;
+/** Define a schema-backed error whose safe presentation can depend on its parsed fields. */
+declare function define<const Tag extends string, const Fields extends Schema.Struct.Fields>(definition: Definition<Tag, Fields>): ErrorClass<Tag, Fields>;
+/** Define the schema, error constructor, user copy, and agent recovery together. */
+export declare const UserFacingError: {
+    define: typeof define;
+    is: (value: unknown) => value is UserFacingError;
+};
+/** Defects get a safe explanation without exposing an arbitrary cause. */
+export declare const UnexpectedError: ErrorClass<"UnexpectedError", {}>;
+export {};